Quick start#

Let’s quickly illustrate how to work with the udlai and what to expect as an outcome.

The following notebook illustrates how to call the UDL Feature API using the library and describes each of the steps to follow.

import udlai

Before we can do anything, we need an authentication token. See udl.ai for more details on how to get one.

token = '12345mytokenfromudl67890' # this is just an illustration, not a working token

Attributes#

Let’s start with an overview of available attributes. We just need to pass the token.

attributes = udlai.attributes(token)

Now we have a pandas DataFrame containing all attributes we have an access to.

attributes.iloc[:5, :5]
id name description short_description unit
0 10 box_length Length of bounding box None m
1 58 Building facade length to street Length of facade that is perceived from street None m
2 60 Building distance neighbor Distance to closest neighboring builinding None m
3 61 Building distance across street Distance to next building in neighboring block... None m
4 62 Perceived courtyards Number of perceived courtyards: Allows for gab... None -

We can also query detials of a single attribute, if we know its ID.

attribute_22 = udlai.attribute_detail(token, attribute_id=22)

The result is a pandas Series.

attribute_22
id                                                                     22
name                                                          obj_compact
description             Compactness of object: C=obj_peri²/(4*box_area*π)
short_description                                                    None
unit                                                                    -
tags.id                                                                 4
tags.name                                                      Morphology
main_tag.id                                                             4
main_tag.name                                                  Morphology
data_version                                                         None
data_last_update                                                     None
data_processor                                                        UDL
source_provider                                            Swiss Topo TLM
source_provider_link    https://www.swisstopo.admin.ch/de/wissen-fakte...
coverage_general                                              Switzerland
epsg_code                                                            2056
min_value                                                        0.960614
max_value                                                       24.141694
standard_deviation                                               0.893447
mean                                                             1.647733
year                                                                 2013
value_formatter                                                      None
dtype: object

Features#

So far, we have not accessed any actual values, just the metadata. But given spatial coordinates (latitude and longitude), we can query UDL.AI platform and retrieve the values of selected attributes for any place in the database. We can query a single attribute or multiple at once. The same applies to coordinates.

Single point and a sigle attribute:

single_point_single_attr = udlai.features(token, latitude=47.37, longitude=8.54, attribute_id=22)
single_point_single_attr
22    2.2064113123322
Name: (47.37, 8.54), dtype: object

Single point and multiple attributes, indexed by name instead on an attribute ID:

single_point_name = udlai.features(token, latitude=47.37, longitude=8.54, attribute_id=[10, 11, 22], index_by="name")
single_point_name
box_length                 104
box_perim                  335
obj_compact    2.2064113123322
Name: (47.37, 8.54), dtype: object

Multiple points and a single attribute (the last point is not in the existing database):

lats = [47.3769267, 47.3769267, 48.3769267]
lons = [8.5497381, 8.5417981, 8.9417981]
multiple_pts = udlai.features(token, latitude=lats, longitude=lons, attribute_id=10)
multiple_pts
/Users/martin/Git/udlai/udlai/features.py:334: UserWarning: Some of the locations are not within the udl.ai database. Have you passed correct coordinates?
  warnings.warn(
latitude longitude 10
0 47.376927 8.549738 294
1 47.376927 8.541798 44
2 48.376927 8.941798 None

Multiple points and a multiple attributes, again indexed by name:

lats = [47.3769267, 47.3769267, 48.3769267]
lons = [8.5497381, 8.5417981, 8.9417981]
ids = [11, 12, 13, 14, 15]
multiple_data = udlai.features(token, latitude=lats, longitude=lons, attribute_id=ids, index_by="name")
multiple_data
/Users/martin/Git/udlai/udlai/features.py:334: UserWarning: Some of the locations are not within the udl.ai database. Have you passed correct coordinates?
  warnings.warn(
latitude longitude box_perim box_width box_width2length circ_area circ_perim
0 47.376927 8.549738 1106 259 0.880952380952381 86215 1041
1 47.376927 8.541798 259 85 0.517647058823529 6860 294
2 48.376927 8.941798 None None None None None

You can query as many coordinates and as many attributes as your token allows.