geo-location-services

1. Synopsis

Python Django services to extract station characterisation information from global geographic and geophysical datasets.

All services provide similar REST interfaces so that they can easily be harvested, e.g. for inclusion into the TOAR database:

.../SERVICE_NAME/?SERVICE_OPTIONS

Valid SERVICE_NAMEs are:

major_road: returns distance to major roads using the OpenStreetMap Overpass interface. Data source: https://www.openstreetmap.org/copyright

population_density, population_number: returns population density from European Commission Joint Research Centre. Citation: Schiavina, Marcello; Freire, Sergio; MacManus, Kytt (2019): GHS-POP R2019A - GHS population grid multitemporal (1975-1990-2000-2015). European Commission, Joint Research Centre (JRC) [Dataset] doi:10.2905/0C6B9751-A71F-4062-830B-43C9F432370F PID: http://data.europa.eu/89h/0c6b9751-a71f-4062-830b-43c9f432370f'

topography_srtm: returns aggregate statistics of topography from NASA Shuttle Radar Topographic Mission (SRTM) 90m database. Jarvis, A., H.I. Reuter, A. Nelson, E. Guevara, 2008, Hole-filled SRTM for the globe Version 4, available from the CGIAR-CSI SRTM 90m Database (http://srtm.csi.cgiar.org)

stable_nightlights: returns aggregate statistics of nightlights from NOAA National Centers for Environmental Information (NCEI). Data source: NOAA National Centers for Environmental Information (NCEI)

ecoregion: returns ecoregions from RESOLVE Biodiversity and Wildlife Solutions. Citation: Eric Dinerstein, David Olson, Anup Joshi, Carly Vynne, Neil D. Burgess, Eric Wikramanayake, Nathan Hahn, Suzanne Palminteri, Prashant Hedao, Reed Noss, Matt Hansen, Harvey Locke, Erle C Ellis, Benjamin Jones, Charles Victor Barber, Randy Hayes, Cyril Kormos, Vance Martin, Eileen Crist, Wes Sechrest, Lori Price, Jonathan E. M. Baillie, Don Weeden, Kieran Suckling, Crystal Davis, Nigel Sizer, Rebecca Moore, David Thau, Tanya Birch, Peter Potapov, Svetlana Turubanova, Alexandra Tyukavina, Nadia de Souza, Lilian Pintea, Jose C. Brito, Othman A. Llewellyn, Anthony G. Miller, Annette Patzelt, Shahina A. Ghazanfar, Jonathan Timberlake, Heinz Klöser, Yara Shennan-Farpon, Roeland Kindt, Jens-Peter Barnekow Lilleso, Paulo van Breugel, Lars Graudal, Maianna Voge, Khalaf F. Al-Shammari, Muhammad Saleem, An Ecoregion-Based Approach to Protecting Half the Terrestrial Realm, BioScience, Volume 67, Issue 6, June 2017, Pages 534–545, https://doi.org/10.1093/biosci/bix014

climatic_zone: returns climatic zones from University of East Anglia Climatic Research Unit. Citation: University of East Anglia Climatic Research Unit; Harris, I.C.; Jones, P.D. (2017): CRU TS4.00: Climatic Research Unit (CRU) Time-Series (TS) version 4.00 of high-resolution gridded data of month-by-month variation in climate (Jan. 1901- Dec. 2015). Centre for Environmental Data Analysis, 25 August 2017. doi:10.5285/edf8febfdaad48abb2cbaf7d7e846a86. http://dx.doi.org/10.5285/edf8febfdaad48abb2cbaf7d7e846a86

nox_emissions: returns nox emissions from CAMS emission datasets. Citation: Granier, C., S. Darras, H. Denier van der Gon, J. Doubalova, N. Elguindi, B. Galle, M. Gauss, M. Guevara, J.-P. Jalkanen, J. Kuenen, C. Liousse, B. Quack, D. Simpson, K. Sindelarova The Copernicus Atmosphere Monitoring Service global and regional emissions (April 2019 version) Report April 2019 version null 2019 Elguindi, Granier, Stavrakou, Darras et al. Analysis of recent anthropogenic surface emissions from bottom-up inventories and top-down estimates: are future emission scenarios valid for the recent past? Earth's Future null submitted 2020

htap_region_tier1: returns HTAP region from Task Force on Hemispheric Transport of Air Pollution. The 'tier1' region defined in the task force on hemispheric transport of air pollution (TFHTAP) coordinated model studies according to figure 4 of https://publications.jrc.ec.europa.eu/repository/bitstream/JRC102552/lbna28255enn.pdf

landcover: returns landcover from ESA and UCLouvain. Citation: ESA. Land Cover CCI Product User Guide Version 2. Tech. Rep. (2017). Available at: http://maps.elie.ucl.ac.be/CCI/viewer/download/ESACCI-LC-Ph2-PUGv2_2.0.pdf

Arguments (not used in all services):

YEAR: year for which to get data, not available for all services

Y: latitude in degrees_north (southern latitudes as negative values)

X: longitude in degrees_east (either -180 to +180 or 0 to 360)

Note: You can also write long or longitude instead of lon, or latitude instead of lat.

OPTIONS:

radius=: radius in m for aggregation of results. Default: 25000, i.e. 25 km. Maximum: 100000, i.e. 100 km.

agg=mean|median|min|max|NN-percentile|sum|stddev: aggregation method. Not available for all services. For example, major-raods will always return the nearest distance to a road. NN-percentile can also be written as NN%-ile.

direction=N|NEN|NE|ENE|E|ESE|SE|SES|S|SWS|SW|WSW|W|WNW|NW|NWN|all|true: restrict search and/or aggregation to specified wind sector. If set to all or true, return result for each wind sector

description=True|False works only for ecoregion and landcover

relative=True|False works only for topography_srtm

Individual services may have additional optional URL parameters.

2. Individual services

2.1 major_road

This service performs a query to the Overpass Web API of Open Street Map and returns the distance and compass angle to the nearest major road from the point location specified by the lat and lon arguments. The response also contains information about the highway type (see definitions) and highway name if available.

OPTIONS:

The radius and direction arguments work as described above. The agg option is ignored.

highway_types=string: specify the Open Street Map highway types to be included in the search. Default is to ask for 'motorway,trunk,primary,secondary,tertiary'. Highway types must be specified as a comma-separated string.

The major_roads service also has a map variant where OpenStreetmap tiles are displayed with an overlay of the search point and the roads surrounding it. The url for this is [base-url]/major_roads/map/[?Options].

2.2 population_density

This service returns the population density for the specified year at the point location specified by the lat and lon arguments or aggregated over a given radius.

OPTIONS:

All arguments can be used as described above. There are no service-specific arguments.

2.3 topography_srtm

This service returns the topographic altitude at the point location specified by the lat and lon arguments or aggregated over a given radius.

OPTIONS:

All arguments can be used as described above.

relative=true|false: specify whether to get the absolute or relative topographic altitude

2.4 stable_nightlights

This service returns the nightlights for the specified year at the point location specified by the lat and lon arguments or aggregated over a given radius.

OPTIONS:

All arguments can be used as described above. There are no service-specific arguments.

2.5 ecoregion

This service returns the ecoregion at the point location specified by the lat and lon arguments.

OPTIONS:

description=true|false: specify whether to get the ecoregion description from a radius or at the point location

All other arguments are ignored except for the radius parameter if description=True.

2.6 climatic_zone

This service returns the climatic zone at the point location specified by the lat and lon arguments.

OPTIONS:

All arguments are ignored.

2.7 nox_emissions

This service returns the nox emissions for the specified year at the point location specified by the lat and lon arguments or aggregated over a given radius.

OPTIONS:

All arguments can be used as described above. There are no service-specific arguments.

2.8 htap_region_tier1

This service returns the HTAP region for the specified lat and country.

OPTIONS:

All arguments are ignored.

2.9 population_number

This service returns the population number for the specified year at the point location specified by the lat and lon arguments or aggregated over a given radius.

OPTIONS:

All arguments can be used as described above. There are no service-specific arguments.

2.10 landcover

This service returns the landcover for the specified year at the point location specified by the lat and lon arguments.

OPTIONS:

description=true|false: specify whether to get the landcover description from a radius or at the point location

All other arguments are ignored except for the radius parameter if description=True.

3. Installation

Python version 3.10 or higher is needed!

Local

• Clone package from https://gitlab.jsc.fz-juelich.de/esde/toar-data/geopeas

• Create a virtual environment and activate

python3 -m venv venv source venv/bin/activate

• Install requirements from file (this includes installation of Django)

pip install -r requirements.txt

• Create or update database and database cache:

python manage.py makemigrations
python manage.py migrate
python manage.py createcachetable

(Note: the tool uses the cache database only for caching OSM query results)

4. Getting started

• Launch application: python manage.py runserver

(Note: when the application shall be launched in production changes in settings.py and a couple more steps will be necessary. Add 0.0.0.0:8080 to launch the application so that it can be viewed in browsers on other machines.)

• click on the link in the terminal, to open GeoPEAS in your browser

• click on the service you want to use

• to see the map display write /map after the service name

http://127.0.0.1:8000/major_road/map/?lat=50&lon=6

5. Acknowledgements

The authors are grateful for funding from the European Research Council (ERC) under the European Union’s Horizon 2020 research and innovation programme (grant agreement No 787576).