Download Module

urbanpy.download.get_hdx_dataset(resources_df: DataFrame, ids: int | list) → DataFrame[source]

HDX dataset download.

Parameters:

  • resources_df (pd.DataFrame) – Resources dataframe from returned by search_hdx_dataset

  • ids (int or list) – IDs in the resources dataframe

Returns:

data – The corresponding dataset in DataFrame format

Return type:

pd.DataFrame

Examples

>>> resources_df = urbanpy.download.search_hdx_dataset('peru')
>>> population_df = urbanpy.download.get_hdx_dataset(resources_df, 0)
>>> population_df
latitude   | longitude  | population_2015 | population_2020
-18.339306 | -70.382361 | 11.318147       | 12.099885
-18.335694 | -70.393750 | 11.318147       | 12.099885
-18.335694 | -70.387361     | 11.318147           | 12.099885
-18.335417 | -70.394028     | 11.318147           | 12.099885
-18.335139 | -70.394306     | 11.318147           | 12.099885
urbanpy.download.hdx_dataset(resource)[source]

Download a dataset from HDX. The allowed formats are CSV (.csv) and zipped CSV (.csv.zip). To run our function we would only copy what is after “https://data.humdata.org/dataset/” to the ‘resource’ parameter.

For example: ‘4e74db39-87f1-4383-9255-eaf8ebceb0c9/resource/317f1c39-8417-4bde-a076-99bd37feefce/download/population_per_2018-10-01.csv.zip’.

Parameters:

resource (str) – Specific address to the HDX dataset resource. Since every dataset is referenced to a diferent resource id, only the base url can be provided by this library.

Returns:

dataset – Contains the requested HDX dataset resource.

Return type:

DataFrame

Examples

>>> hdx_data = hdx_dataset('4e74db39-87f1-4383-9255-eaf8ebceb0c9/resource/317f1c39-8417-4bde-a076-99bd37feefce/download/population_per_2018-10-01.csv.zip')
>>> hdx_data.head()
latitude   | longitude  | population_2015 | population_2020
-18.339306 | -70.382361 | 11.318147       | 12.099885
-18.335694 | -70.393750 | 11.318147       | 12.099885
-18.335694 | -70.387361     | 11.318147           | 12.099885
-18.335417 | -70.394028     | 11.318147           | 12.099885
-18.335139 | -70.394306     | 11.318147           | 12.099885
urbanpy.download.hdx_fb_population(country, map_type)[source]

Download population density maps from Facebook HDX.

Parameters:

  • country (str. One of {'argentina', 'bolivia', 'brazil', 'chile', 'colombia', 'ecuador', 'paraguay', 'peru', 'uruguay'}) – Input country to download data from.

  • map_type (str. One of {'full', 'children', 'youth', 'elderly'}) – Input population map to download.

Returns:

population – DataFrame with lat, lon, and population columns. Coordinates are in EPSG 4326.

Return type:

DataFrame

Examples

>>> urbanpy.download.hdx_fb_population('peru', 'full')
latitude   | longitude  | population_2015 | population_2020
-18.339306 | -70.382361 | 11.318147       | 12.099885
-18.335694 | -70.393750 | 11.318147       | 12.099885
-18.335694 | -70.387361     | 11.318147           | 12.099885
-18.335417 | -70.394028     | 11.318147           | 12.099885
-18.335139 | -70.394306     | 11.318147           | 12.099885
urbanpy.download.nominatim_osm(query: str, expected_position: int | None = 0, email: str = '') → GeoDataFrame[source]

Download OpenStreetMaps data for a specific city.

Parameters:

  • query (str) – Query string for OSM data to be downloaded (e.g. “Lima, Peru”).

  • expected_position (int 0:n) – Expected position of the polygon data within the Nominatim results. Default 0 returns the first result. If set to None, all the results are returned.

Returns:

gdf – GeoDataFrame with the fetched OSM data.

Return type:

GeoDataFrame

Examples

>>> lima = nominatim_osm('Lima, Peru', 2)
>>> lima.head()
geometry     | place_id      | osm_type     | osm_id     | display_name     | place_rank  |  category | type               | importance     | icon
MULTIPOLYGON | 235480647 | relation | 1944670.0  | Lima, Peru       | 12          |  boundary |     administrative | 0.703484       | https://nominatim.openstreetmap.org/images/map...
urbanpy.download.osmnx_graph(download_type: str, network_type='drive', query_str=None, geom=None, distance=None, **kwargs)[source]

Download a graph from OSM using osmnx.

Parameters:

  • download_type (str. One of {'polygon', 'place', 'point'}) – Input download type. If polygon, the polygon parameter must be provided as a Shapely Polygon.

  • network_type (str. One of {'drive', 'drive_service', 'walk', 'bike', 'all', 'all_private'}) – Network type to download. Defaults to drive.

  • query_str (str (Optional).) – Only requiered for place type downloads. Query string to download a network.

  • polygon (Shapely Polygon or Point (Optional).) – Polygon requiered for polygon type downloads, Point for place downloads. Polygons are used as bounds for network download, points as the center. with a distance buffer.

  • distance (int) – Distance in meters to use as buffer from a point to download the network.

Returns:

G – Requested graph with simplyfied geometries.

Return type:

networkx.MultiDiGraph

Examples

>>> poly = urbanpy.download.nominatim_osm('San Isidro, Peru')
>>> G = urbanpy.download.osmnx_graph('polygon', geom=lima.loc[0,'geometry'])
>>> G
<networkx.classes.multidigraph.MultiDiGraph at 0x1a2ba08150>
urbanpy.download.overpass(type_of_data: str, query: dict, mask: GeoDataFrame | GeoSeries | Polygon | MultiPolygon) → Tuple[GeoDataFrame, DataFrame | None][source]

Download geographic data using Overpass API.

Parameters:

  • type_of_data (str) – One of {‘node’, ‘way’, ‘relation’, ‘rel’}. OSM Data structure to be queried from Overpass API.

  • query (dict) – Dict containing OSM tag filters. Dict keys can take OSM tags and Dict values can be a list of strings, str, or None. Example: { ‘key0’: [‘v0a’, ‘v0b’, ‘v0c’], ‘key1’: ‘v1’, ‘key2’: None } Check keys [OSM Map Features](https://wiki.openstreetmap.org/wiki/Map_features).

  • mask (GeoDataFrame, GeoSeries, Polygon, or MultiPolygon) – Total bounds of mask to be used for the query.

Returns:

  • gdf (GeoDataFrame) – POIs from the selected type of facility.

  • df (DataFrame) – Relations metadata such as ID and tags. Returns None if ‘type_of_data’ is other than ‘relation’.

urbanpy.download.overpass_pois(bounds, facilities=None, custom_query=None)[source]

Download POIs using Overpass API.

Parameters:

  • bounds (array_like) – Input bounds for query. Follows [minx,miny,maxx,maxy] pattern.

  • facilities (str. One of {'food', 'health', 'education', 'finance'}) – Type of facilities to download according to HOTOSM types. Based on this a different type of query is constructed.

  • custom_query (str (Optional). Default None.) – String with custom Overpass QL query (See https://wiki.openstreetmap.org/wiki/Overpass_API/Language_Guide). If this parameter is diferent than None, bounds and facilities values are ignored.

Returns:

  • gdf (GeoDataFrame) – POIs from the selected type of facility. If ‘custom_query’ is given response is returned instead of gdf.

  • response (request.Response) – Returned only if ‘custom_query’ is given. Contains the server’s response to the HTTP request from the Overpass API Server.

Examples

>>> lima = nominatim_osm('Lima, Peru', 2)
>>> urbanpy.download.overpass_pois(lima.total_bounds, 'health')
type |  id        | lat           | lon            | tags                                              | geometry                   | poi_type
node |      367826732 |     -0.944005 |     -80.733941 | {'amenity': 'pharmacy', 'name': 'Fybeca'}         | POINT (-80.73394 -0.94401)     | pharmacy
node |      367830051 |     -0.954086 |     -80.742420 | {'amenity': 'hospital', 'emergency': 'yes', 'n... | POINT (-80.74242 -0.95409)     | hospital
node |      367830065 |     -0.954012 |     -80.741554 | {'amenity': 'hospital', 'name': 'Clínica del S... | POINT (-80.74155 -0.95401)     | hospital
node |      367830072 |     -0.953488 |     -80.740739 | {'amenity': 'hospital', 'name': 'Clínica Cente... | POINT (-80.74074 -0.95349)     | hospital
node |      3206491590|     -1.040708 |     -80.665107 | {'amenity': 'hospital', 'name': 'Clínica Monte... | POINT (-80.66511 -1.04071)     | hospital
urbanpy.download.search_hdx_dataset(country: str, repository='high-resolution-population-density-maps-demographic-estimates')[source]

Dataset search within HDX repositories. Defaults to population density maps.

Parameters:

  • country (str) – Country to search datasets

  • resource (str) – Resource type within the HDX database

Returns:

datasets – DataFrame of available datasets within HDX

Return type:

DataFrame

Examples

>>> resources_df = urbanpy.download.search_hdx_dataset('peru')
>>> resources_df
   | created        | name                                              | population                                    | size_mb | url
id |                        |                                                       |                                           |         |
0  | 2019-06-11     | population_per_2018-10-01.csv.zip                     | Overall population density                | 19.36       | https://data.humdata.org/dataset/4e74db39-87f1...
2  | 2019-06-11     | PER_children_under_five_2019-06-01_csv.zip        | Children (ages 0-5)                           | 16.60       | https://data.humdata.org/dataset/4e74db39-87f1...
4  | 2019-06-11     | PER_elderly_60_plus_2019-06-01_csv.zip                | Elderly (ages 60+)                        | 16.59       | https://data.humdata.org/dataset/4e74db39-87f1...
6  | 2019-06-11     | PER_men_2019-06-01_csv.zip                        | Men                                           | 16.64       | https://data.humdata.org/dataset/4e74db39-87f1...
8  | 2019-06-11     | PER_women_2019-06-01_csv.zip                      | Women                                         | 16.63       | https://data.humdata.org/dataset/4e74db39-87f1...
10 | 2019-06-11     | PER_women_of_reproductive_age_15_49_2019-06-01... | Women of reproductive age (ages 15-49)    | 16.62   | https://data.humdata.org/dataset/4e74db39-87f1...
12 | 2019-06-11     | PER_youth_15_24_2019-06-01_csv.zip                | Youth (ages 15-24)                            | 16.61       | https://data.humdata.org/dataset/4e74db39-87f1...