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

population_density: returns population density from European Commission Joint Research Centre

topography_srtm: returns aggregate statistics of topography from NASA Shuttle Radar Topographic Mission (SRTM) 90m database

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

ecoregion: returns ecoregions from RESOLVE Biodiversity and Wildlife Solutions

climatic_zone: returns climatic zones from University of East Anglia Climatic Research Unit

nox_emissions: returns nox emissions from CAMS emission datasets

htap_region_tier1: returns HTAP region from Task Force on Hemispheric Transport of Air Pollution

population_number: returns population number from European Commission Joint Research Centre

landcover: returns landcover from ESA and UCLouvain

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

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/geolocationservices

• 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)

• 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.)

4. Authors

Lukas H. Leufen, Niklas Selke, Martin G. Schultz, Jan Vogelsang, and Sabine Schröder, Jülich Supercomputing Centre, Forschungszentrum Jülich, Germany

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).