{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Quick start\n", "\n", "Let's quickly illustrate how to work with the `udlai` and what to expect as an outcome.\n", "\n", "The following notebook illustrates how to call the UDL Feature API using the library and describes each of the steps to follow." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "import udlai" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Before we can do anything, we need an authentication token. See [udl.ai](https://udl.ai) for more details on how to get one." ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "token = '2854d7073ad847f69ab0bf576132e064726b8b77' # this is just an illustration, not a working token" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Attributes\n", "\n", "Let's start with an overview of available attributes. We just need to pass the token." ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [], "source": [ "attributes = udlai.attributes(token)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we have a pandas DataFrame containing all attributes we have an access to." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idnamedescriptionshort_descriptionunittags.idtags.namemain_tag.idmain_tag.namedata_version...source_providersource_provider_linkcoverage_generalepsg_codemin_valuemax_valuestandard_deviationmeanyearvalue_formatter
099Area accessible 2min drivingCatchment area accessible in 2 min freeflow dr...Nonem²105Morphology105Morphology2016...Swiss Topo TLMhttps://www.swisstopo.admin.ch/de/wissen-fakte...Switzerland2056.08.025263465.0834619.117500488624.4201002016None
1242Usefit for residentialPotential for residential usage. The predictio...Noneprob113Real Estate Market113Real Estate Market2016...UDLNoneNone2056.00.01.00.3000000.8300002016None
2287Pre-school distanceAir distance to next pre-school.Nonem111Points of Interest111Points of Interest2016...BFShttps://www.bfs.admin.ch/bfs/de/home/statistik...None2056.00.034605.03520.0000003239.0000002016None
3293Distance primary schoolDistance to next primary school.Nonem111Points of Interest111Points of Interest2016...BFShttps://www.bfs.admin.ch/bfs/de/home/statistik...None2056.00.020000.0370.000000700.0000002016None
4140Slope of TerrainSlope of terrain.Nonedegree106Topography106Topography2016...Swiss Topo TLMhttps://www.swisstopo.admin.ch/de/geodata/heig...None2056.00.035.04.3833864.6001482016None
5172Leisure activties in 300mLeisure activities in 300m.None-111Points of Interest111Points of Interest2016...BFShttps://www.bfs.admin.ch/bfs/de/home/statistik...None2056.00.0133.03.9081460.8267992016None
6166Public transport distanceAir distance to next public transport stop.Nonem111Points of Interest111Points of Interest2017...SBBhttps://opentransportdata.swiss/dataset/bhlistNone2056.00.02750.0397.933136530.3535482017None
7288Distance secondary schoolDistance secondary schoolNone[m]111Points of Interest111Points of InterestNone...NoneNoneNoneNaN0.037884.03822.0000004044.000000NoneNone
8289Usefit CommercialUsefit CommercialNoneprob113Real Estate Market113Real Estate MarketNone...NoneNoneNoneNaN0.01.00.3000000.100000NoneNone
9169Retail store distanceAir distance to next retail store.Nonem111Points of Interest111Points of Interest2016...BFShttps://www.bfs.admin.ch/bfs/de/home/statistik...None2056.00.04720.0648.4619631024.7483562016None
10171Retail stores in 300mDensity of retail within 300m.None-111Points of Interest111Points of Interest2016...BFShttps://www.bfs.admin.ch/bfs/de/home/statistik...None2056.00.09.00.5836210.1670012016None
\n", "

11 rows × 22 columns

\n", "
" ], "text/plain": [ " id name \\\n", "0 99 Area accessible 2min driving \n", "1 242 Usefit for residential \n", "2 287 Pre-school distance \n", "3 293 Distance primary school \n", "4 140 Slope of Terrain \n", "5 172 Leisure activties in 300m \n", "6 166 Public transport distance \n", "7 288 Distance secondary school \n", "8 289 Usefit Commercial \n", "9 169 Retail store distance \n", "10 171 Retail stores in 300m \n", "\n", " description short_description \\\n", "0 Catchment area accessible in 2 min freeflow dr... None \n", "1 Potential for residential usage. The predictio... None \n", "2 Air distance to next pre-school. None \n", "3 Distance to next primary school. None \n", "4 Slope of terrain. None \n", "5 Leisure activities in 300m. None \n", "6 Air distance to next public transport stop. None \n", "7 Distance secondary school None \n", "8 Usefit Commercial None \n", "9 Air distance to next retail store. None \n", "10 Density of retail within 300m. None \n", "\n", " unit tags.id tags.name main_tag.id main_tag.name \\\n", "0 m² 105 Morphology 105 Morphology \n", "1 prob 113 Real Estate Market 113 Real Estate Market \n", "2 m 111 Points of Interest 111 Points of Interest \n", "3 m 111 Points of Interest 111 Points of Interest \n", "4 degree 106 Topography 106 Topography \n", "5 - 111 Points of Interest 111 Points of Interest \n", "6 m 111 Points of Interest 111 Points of Interest \n", "7 [m] 111 Points of Interest 111 Points of Interest \n", "8 prob 113 Real Estate Market 113 Real Estate Market \n", "9 m 111 Points of Interest 111 Points of Interest \n", "10 - 111 Points of Interest 111 Points of Interest \n", "\n", " data_version ... source_provider \\\n", "0 2016 ... Swiss Topo TLM \n", "1 2016 ... UDL \n", "2 2016 ... BFS \n", "3 2016 ... BFS \n", "4 2016 ... Swiss Topo TLM \n", "5 2016 ... BFS \n", "6 2017 ... SBB \n", "7 None ... None \n", "8 None ... None \n", "9 2016 ... BFS \n", "10 2016 ... BFS \n", "\n", " source_provider_link coverage_general \\\n", "0 https://www.swisstopo.admin.ch/de/wissen-fakte... Switzerland \n", "1 None None \n", "2 https://www.bfs.admin.ch/bfs/de/home/statistik... None \n", "3 https://www.bfs.admin.ch/bfs/de/home/statistik... None \n", "4 https://www.swisstopo.admin.ch/de/geodata/heig... None \n", "5 https://www.bfs.admin.ch/bfs/de/home/statistik... None \n", "6 https://opentransportdata.swiss/dataset/bhlist None \n", "7 None None \n", "8 None None \n", "9 https://www.bfs.admin.ch/bfs/de/home/statistik... None \n", "10 https://www.bfs.admin.ch/bfs/de/home/statistik... None \n", "\n", " epsg_code min_value max_value standard_deviation mean year \\\n", "0 2056.0 8.0 25263465.0 834619.117500 488624.420100 2016 \n", "1 2056.0 0.0 1.0 0.300000 0.830000 2016 \n", "2 2056.0 0.0 34605.0 3520.000000 3239.000000 2016 \n", "3 2056.0 0.0 20000.0 370.000000 700.000000 2016 \n", "4 2056.0 0.0 35.0 4.383386 4.600148 2016 \n", "5 2056.0 0.0 133.0 3.908146 0.826799 2016 \n", "6 2056.0 0.0 2750.0 397.933136 530.353548 2017 \n", "7 NaN 0.0 37884.0 3822.000000 4044.000000 None \n", "8 NaN 0.0 1.0 0.300000 0.100000 None \n", "9 2056.0 0.0 4720.0 648.461963 1024.748356 2016 \n", "10 2056.0 0.0 9.0 0.583621 0.167001 2016 \n", "\n", " value_formatter \n", "0 None \n", "1 None \n", "2 None \n", "3 None \n", "4 None \n", "5 None \n", "6 None \n", "7 None \n", "8 None \n", "9 None \n", "10 None \n", "\n", "[11 rows x 22 columns]" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "attributes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can also query detials of a single attribute, if we know its ID." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "attribute_298 = udlai.attribute_detail(token, attribute_id=289)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The result is a pandas Series." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "id 289\n", "name Usefit Commercial\n", "description Usefit Commercial\n", "short_description None\n", "unit prob\n", "tags.id 113\n", "tags.name Real Estate Market\n", "main_tag.id 113\n", "main_tag.name Real Estate Market\n", "data_version None\n", "data_last_update None\n", "data_processor None\n", "source_provider None\n", "source_provider_link None\n", "coverage_general None\n", "epsg_code None\n", "min_value 0.0\n", "max_value 1.0\n", "standard_deviation 0.3\n", "mean 0.1\n", "year None\n", "value_formatter None\n", "dtype: object" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "attribute_289" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Features\n", "\n", "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.\n", "\n", "Single point and a sigle attribute:" ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "99 1114508\n", "Name: (47.37, 8.54), dtype: object" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "single_point_single_attr = udlai.features(token, latitude=47.37, longitude=8.54, attribute_id=99)\n", "single_point_single_attr" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " Single point and multiple attributes, indexed by name instead on an attribute ID:" ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "289 0.922094166278839\n", "99 1114508\n", "Name: (47.37, 8.54), dtype: object" ] }, "execution_count": 13, "metadata": {}, "output_type": "execute_result" } ], "source": [ "single_point_name = udlai.features(token, latitude=47.37, longitude=8.54, attribute_id=[289, 99], index_by=\"id\")\n", "single_point_name" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Multiple points and a single attribute (the last point is not in the existing database):" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "/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?\n", " warnings.warn(\n" ] }, { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
latitudelongitude28999
047.3769278.5497380.950480580329895801361
147.3769278.5417980.917928218841553606369
248.3769278.941798NoneNone
\n", "
" ], "text/plain": [ " latitude longitude 289 99\n", "0 47.376927 8.549738 0.950480580329895 801361\n", "1 47.376927 8.541798 0.917928218841553 606369\n", "2 48.376927 8.941798 None None" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "lats = [47.3769267, 47.3769267, 48.3769267]\n", "lons = [8.5497381, 8.5417981, 8.9417981]\n", "multiple_pts = udlai.features(token, latitude=lats, longitude=lons, attribute_id=[289, 99])\n", "multiple_pts" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Multiple points and a multiple attributes, again indexed by name:" ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "/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?\n", " warnings.warn(\n" ] }, { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
latitudelongitudenet_prox_sizeusefit_resdntretail_300usefit_com
047.3769278.5497388013610.029629353433847400.950480580329895
147.3769278.5417986063690.028497328981757250.917928218841553
248.3769278.941798NoneNoneNoneNone
\n", "
" ], "text/plain": [ " latitude longitude net_prox_size usefit_resdnt retail_300 \\\n", "0 47.376927 8.549738 801361 0.0296293534338474 0 \n", "1 47.376927 8.541798 606369 0.0284973289817572 5 \n", "2 48.376927 8.941798 None None None \n", "\n", " usefit_com \n", "0 0.950480580329895 \n", "1 0.917928218841553 \n", "2 None " ] }, "execution_count": 16, "metadata": {}, "output_type": "execute_result" } ], "source": [ "lats = [47.3769267, 47.3769267, 48.3769267]\n", "lons = [8.5497381, 8.5417981, 8.9417981]\n", "ids = [99, 242, 171, 289]\n", "multiple_data = udlai.features(token, latitude=lats, longitude=lons, attribute_id=ids, index_by=\"name\")\n", "multiple_data" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can query as many coordinates and as many attributes as your token allows." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Summary statistics over an area\n", "\n", "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." ] }, { "cell_type": "code", "execution_count": 24, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
maxmeanmedianminstdsum
Usefit for residential0.9772970.3657540.2385650.0085580.35167353.034321
\n", "
" ], "text/plain": [ " max mean median min std \\\n", "Usefit for residential 0.977297 0.365754 0.238565 0.008558 0.351673 \n", "\n", " sum \n", "Usefit for residential 53.034321 " ] }, "execution_count": 24, "metadata": {}, "output_type": "execute_result" } ], "source": [ "geojson = {\n", " \"type\": \"Polygon\",\n", " \"coordinates\": [\n", " [\n", " [8.5367, 47.3712],\n", " [8.5406, 47.3712],\n", " [8.5406, 47.3739],\n", " [8.5367, 47.3739],\n", " [8.5367, 47.3712],\n", " ]\n", " ],\n", "}\n", "agg = udlai.aggregates(token, geojson, 242, index_by=\"name\")\n", "agg" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3.9.13 ('geo_dev')", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.5" }, "orig_nbformat": 4, "vscode": { "interpreter": { "hash": "8d1b2c984ad473d756980598d6fae8279815dc9c89a9d51a262cfb04eba7ee8f" } } }, "nbformat": 4, "nbformat_minor": 2 }