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 = '2854d7073ad847f69ab0bf576132e064726b8b77' # 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
id name description short_description unit tags.id tags.name main_tag.id main_tag.name data_version ... source_provider source_provider_link coverage_general epsg_code min_value max_value standard_deviation mean year value_formatter
0 99 Area accessible 2min driving Catchment area accessible in 2 min freeflow dr... None 105 Morphology 105 Morphology 2016 ... Swiss Topo TLM https://www.swisstopo.admin.ch/de/wissen-fakte... Switzerland 2056.0 8.0 25263465.0 834619.117500 488624.420100 2016 None
1 242 Usefit for residential Potential for residential usage. The predictio... None prob 113 Real Estate Market 113 Real Estate Market 2016 ... UDL None None 2056.0 0.0 1.0 0.300000 0.830000 2016 None
2 287 Pre-school distance Air distance to next pre-school. None m 111 Points of Interest 111 Points of Interest 2016 ... BFS https://www.bfs.admin.ch/bfs/de/home/statistik... None 2056.0 0.0 34605.0 3520.000000 3239.000000 2016 None
3 293 Distance primary school Distance to next primary school. None m 111 Points of Interest 111 Points of Interest 2016 ... BFS https://www.bfs.admin.ch/bfs/de/home/statistik... None 2056.0 0.0 20000.0 370.000000 700.000000 2016 None
4 140 Slope of Terrain Slope of terrain. None degree 106 Topography 106 Topography 2016 ... Swiss Topo TLM https://www.swisstopo.admin.ch/de/geodata/heig... None 2056.0 0.0 35.0 4.383386 4.600148 2016 None
5 172 Leisure activties in 300m Leisure activities in 300m. None - 111 Points of Interest 111 Points of Interest 2016 ... BFS https://www.bfs.admin.ch/bfs/de/home/statistik... None 2056.0 0.0 133.0 3.908146 0.826799 2016 None
6 166 Public transport distance Air distance to next public transport stop. None m 111 Points of Interest 111 Points of Interest 2017 ... SBB https://opentransportdata.swiss/dataset/bhlist None 2056.0 0.0 2750.0 397.933136 530.353548 2017 None
7 288 Distance secondary school Distance secondary school None [m] 111 Points of Interest 111 Points of Interest None ... None None None NaN 0.0 37884.0 3822.000000 4044.000000 None None
8 289 Usefit Commercial Usefit Commercial None prob 113 Real Estate Market 113 Real Estate Market None ... None None None NaN 0.0 1.0 0.300000 0.100000 None None
9 169 Retail store distance Air distance to next retail store. None m 111 Points of Interest 111 Points of Interest 2016 ... BFS https://www.bfs.admin.ch/bfs/de/home/statistik... None 2056.0 0.0 4720.0 648.461963 1024.748356 2016 None
10 171 Retail stores in 300m Density of retail within 300m. None - 111 Points of Interest 111 Points of Interest 2016 ... BFS https://www.bfs.admin.ch/bfs/de/home/statistik... None 2056.0 0.0 9.0 0.583621 0.167001 2016 None

11 rows × 22 columns

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

attribute_298 = udlai.attribute_detail(token, attribute_id=289)

The result is a pandas Series.

attribute_289
id                                     289
name                     Usefit Commercial
description              Usefit Commercial
short_description                     None
unit                                  prob
tags.id                                113
tags.name               Real Estate Market
main_tag.id                            113
main_tag.name           Real Estate Market
data_version                          None
data_last_update                      None
data_processor                        None
source_provider                       None
source_provider_link                  None
coverage_general                      None
epsg_code                             None
min_value                              0.0
max_value                              1.0
standard_deviation                     0.3
mean                                   0.1
year                                  None
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=99)
single_point_single_attr
99    1114508
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=[289, 99], index_by="id")
single_point_name
289    0.922094166278839
99               1114508
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=[289, 99])
multiple_pts
/Users/martin/Git/udlai/udlai/feature_api.py:338: UserWarning: Some of the locations are not within the udl.ai database. Have you passed correct coordinates?
  warnings.warn(
latitude longitude 289 99
0 47.376927 8.549738 0.950480580329895 801361
1 47.376927 8.541798 0.917928218841553 606369
2 48.376927 8.941798 None 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 = [99, 242, 171, 289]
multiple_data = udlai.features(token, latitude=lats, longitude=lons, attribute_id=ids, index_by="name")
multiple_data
/Users/martin/Git/udlai/udlai/feature_api.py:338: UserWarning: Some of the locations are not within the udl.ai database. Have you passed correct coordinates?
  warnings.warn(
latitude longitude net_prox_size usefit_resdnt retail_300 usefit_com
0 47.376927 8.549738 801361 0.0296293534338474 0 0.950480580329895
1 47.376927 8.541798 606369 0.0284973289817572 5 0.917928218841553
2 48.376927 8.941798 None None None None

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

Summary statistics over an area#

You can also query a summary statistics over a given area. That can be passed as a shapely.geometry Polygon or MultiPolygon in EPSG:4326 or as a GeoJSON representation.

geojson = {
    "type": "Polygon",
    "coordinates": [
        [
            [8.5367, 47.3712],
            [8.5406, 47.3712],
            [8.5406, 47.3739],
            [8.5367, 47.3739],
            [8.5367, 47.3712],
        ]
    ],
}
agg = udlai.aggregates(token, geojson, 242, index_by="name")
agg
max mean median min std sum
Usefit for residential 0.977297 0.365754 0.238565 0.008558 0.351673 53.034321