API reference#

Feature API#

udlai.attributes(token)#

Returns the all of the attributes that user has access to. User is assigned to token on creation and the list of attributes is managed by the UDL administrator, if you would like to have access to other attributes, please contact UDL.

See the documentation of the underlying REST API https://api.udl.ai/api/v1/docs/public/attributes#operation/attributes_list

Parameters:

tokenstr: API token assigned to a user

Returns:

attributespandas.DataFrame: pandas.DataFrame with attributes and their metadata

Examples

>>> udlai.attributes(token)
      id  ... value_formatter.options.multiply
   10  ...                              NaN
   58  ...                              NaN
   60  ...                              NaN
   61  ...                              NaN
   62  ...                              NaN
..   ...  ...                              ...
284  ...                              NaN
285  ...                              NaN
286  ...                              NaN
287  ...                              NaN
288  ...                              1.0
[243 rows x 31 columns]

udlai.attribute_detail(token, attribute_id)#

Fetch single entity of attribute based on the ID of the attribute provided as a parameter.

See the documentation of the underlying REST API https://api.udl.ai/api/v1/docs/public/attributes#operation/attributes_read

Parameters:

tokenstr: API token assigned to a user
attribute_idint: ID of the queried attribute. Use udlai.attributes to get a list of IDs

Returns:

attribute_detailspandas.Series

Examples

>>> udlai.attribute_detail(token, 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

udlai.features(token, latitude, longitude, attribute_id, index_by='id', grid_size=25)#

An API Endpoint that will return the attributes for provided coordinates. The API expects the attribute IDs, that can be fetched using udlai.attributes function.

You can pass individual coordinates or arrays of the same length.

https://api.udl.ai/api/v1/docs/public/attributes#tag/features

Parameters:

tokenstr: API token assigned to a user
latitudefloat or list-like: latitude or list-like of latitudes denoting the location(s) for a query
longitudefloat or list-like: longitude or list-like of longitudes denoting the location(s) for a query
attribute_idint or list-like: ID(s) of the queried attribute. Use udlai.attributes to get a list of IDs.
index_by{“id”, “name”}: One of the {"id", "name"} denoting whether the output should be indexed using the original attribute ID or its name
grid_size{25, 75, 225, 675}: Resolution of the UDL grid to be queried. Smaller resolutions are more precise but may contain gaps, larger resolutions are aggregated and are more likely to cover entirety of built up area.

Returns:

featurespandas.Series or pandas.DataFrame: returns Series for a single point or a DataFrame for multiple points

Examples

Single point and a single attribute:

>>> udlai.features(token, 47.37, 8.54, 22)
22    2.2064113123322
Name: (47.37, 8.54), dtype: object

Single point and multiple attributes, indexed by name

>>> udlai.features(token, 47.37, 8.54, [10, 11, 22], index_by="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 outside of the covered area):

>>> lats = [47.3769267, 47.3769267, 48.3769267]
>>> lons = [8.5497381, 8.5417981, 8.9417981]
>>> udlai.features(token, lats, lons, 10)
    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 (the last point is outside of the covered area):

>>> lats = [47.3769267, 47.3769267, 48.3769267]
>>> lons = [8.5497381, 8.5417981, 8.9417981]
>>> ids = [11, 12, 13, 14, 15, 16, 22]
>>> udlai.features(token, lats, lons, ids)
    latitude  longitude    11    12  ...     14    15    16                22
0  47.376927   8.549738  1106   259  ...  86215  1041   166  13.1956982144114
1  47.376927   8.541798   259    85  ...   6860   294    47  1.60758471341658
2  48.376927   8.941798  None  None  ...   None  None  None              None
[3 rows x 9 columns]

udlai.aggregates(token, geometry, attribute_id, index_by='id', grid_size=25)#

An API Endpoint that will return the aggregates for provided geometry. The API expects the attribute IDs, that can be fetched using udlai.attributes function.

You can pass a GeoJSON-encoded Polygon or MultiPolygon or a shapely.geometry.

https://api.udl.ai/api/v1/docs/public/attributes#tag/aggregates

Parameters:

tokenstr: API token assigned to a user
geometryGeoJSON-like dict or shapely.geometry: Polygon or MultiPolygon geometry denoting the area of interest
attribute_idint or list-like: ID(s) of the queried attribute. Use udlai.attributes to get a list of IDs.
index_by{“id”, “name”}: One of the {"id", "name"} denoting whether the output should be indexed using the original attribute ID or its name
grid_size{25, 75, 225, 675}: Size of the grid to be queried.

Returns:

aggregatespandas.DataFrame

Examples

Shapely geometry and a single attribute.

>>> udlai.aggregates(token, shapely_geom, 10)
    max       mean  median   min        std      sum
10  135.0  94.313869    94.0  19.0  30.600546  12921.0

Shapely geometry and a single attribute indexed by its name.

>>> udlai.aggregates(token, shapely_geom, 10, index_by="name")
              max       mean  median   min        std      sum
box_length  135.0  94.313869    94.0  19.0  30.600546  12921.0

Shapely geometry and a mutliple attributes indexed by their ID.

>>> udlai.aggregates(token, shapely_geom, [10, 12])
        sum       mean  median   min    max        std
10  12921.0  94.313869    94.0  19.0  135.0  30.600546
12  13118.0  95.751825   100.0  29.0  142.0  30.870646

Shapely geometry and a mutliple attributes indexed by their names.

>>> udlai.aggregates(token, shapely_geom, [10, 12], index_by='name')
                sum       mean  median   min    max        std
box_length  12921.0  94.313869    94.0  19.0  135.0  30.600546
box_width   13118.0  95.751825   100.0  29.0  142.0  30.870646

GeoJSON-encoded geometry:

>>> geojson = {
...     "type": "Polygon",
...     "coordinates": [
...         [
...             [8.5367, 47.3712],
...             [8.5406, 47.3712],
...             [8.5406, 47.3739],
...             [8.5367, 47.3739],
...             [8.5367, 47.3712],
...         ]
...     ],
... }
>>> udlai.aggregates(token, geojson, 10)
    max       mean  median   min        std      sum
10  135.0  94.268966    94.0  19.0  30.613916  13669.0

Geocoding API#

udlai.geocode_structured(token, df)#

Geocode addresses from a semantically structured DataFrame.

The DataFrame must have four columns ["street", "number", "postcode", "town"] (no more, no less) following this example:

          street  number  postcode    town
0  Riedgrabenweg      15      8050  Zurich
1  Butzenstrasse      35      8038  Zurich

It returns the addresses as they are known in the database with a score denoting the quality of match between the original and the geocoded address. Score 1 means 1:1 match, score 0 means no match.

Parameters:

tokenstr: API token assigned to a user
dfDataFrame: DataFrame containing the structured addresses following the example above.

Returns:

pandas.DataFrame: DataFrame with the geocoded address (not the original) and the matching score

Examples

>>> df = pd.DataFrame(
...     {
...         "street": {0: "Riedgrabenweg", 1: "Butzenstrasse"},
...         "number": {0: 15, 1: 35},
...         "postcode": {0: 8050, 1: 8038},
...         "town": {0: "Zurich", 1: "Zurich"},
...     }
... )
>>> df
          street  number  postcode    town
0  Riedgrabenweg      15      8050  Zurich
1  Butzenstrasse      35      8038  Zurich

>>> udlai.geocode_structured(token, df)
          street number postcode     town   latitude  longitude     score
0  riedgrabenweg     15     8050  zuerich  47.406742   8.558574  0.980769
1  butzenstrasse     35     8038  zuerich  47.340733   8.526516  0.980769

udlai.geocode_unstructured(token, addresses)#

Geocode addresses from an unstructred string

If you have a single string representing the whole address, use this function.

It returns the addresses as they are known in the database with a score denoting the quality of match between the original and the geocoded address. Score 1 means 1:1 match, score 0 means no match.

Parameters:

tokenstr: API token assigned to a user
addresseslist: list of strings representing addresses

Returns:

pandas.DataFrame: DataFrame with the geocoded address (not the original) and the matching score

Examples

>>> addresses = [
...     "Riedgrabenweg 15, 8050 Zürich",
...     "Butzenstrasse 35, 8038 Zürich, Switzerland",
... ]
>>> udlai.geocode_unstructured(token, addresses)
          street number postcode     town   latitude  longitude     score
0  riedgrabenweg     15     8050  zuerich  47.406742   8.558574  0.942308
1  butzenstrasse     35     8038  zuerich  47.340733   8.526516  0.942308