openelevationservice is a Flask application which extracts elevation from various elevation datasets for Point or LineString 2D geometries and returns 3D geometries in various formats.
Supported formats are:
- GeoJSON
- Polyline, i.e. list of vertices
- Google's encoded polyline
- Point, i.e. one vertex
For general support and questions, please contact our forum. After successful installation, you can also find a API documentation locally at https://localhost:5000/apidocs, provided via flasgger.
For issues and improvement suggestions, use the repo's issue tracker.
This service is part of the GIScience software stack, crafted at HeiGIT institute at the University of Heidelberg.
You can also use our free API via (also check Endpoints for usage):
- https://api.openrouteservice.org/elevation/point?api_key=YOUR_KEY
- https://api.openrouteservice.org/elevation/line?api_key=YOUR_KEY
You can either run this service on a host machine (like your PC) in a virtual environment or via docker (recommended).
- Docker
- PostGIS installation (recommended Kartoza's docker)
- Customize
ops_settings_docker.sample.ymlto your needs and name itops_settings_docker.yml - Build container
sudo docker-compose up -d - Create the database
sudo docker exec -it <container ID> bash -c "source /oes_venv/bin/activate; export OES_LOGLEVEL=DEBUG; flask create"- Download SRTM data
sudo docker exec -it <container ID> bash -c "source /oes_venv/bin/activate; export OES_LOGLEVEL=DEBUG; flask download --xyrange=0,0,73,25"The optional xyrange parameter specfies the minx,miny,maxx,maxy indices of the available tiles, default is 0,0,73,25. You can see a representation of indices in the map on the CGIAR website.
Note, that you need to have credentials to access the FTP site , which you can request here.
- Import SRTM data
sudo docker exec -it <container ID> bash -c "source /oes_venv/bin/activate; flask importdata"The import command will import whatever .tif files it finds in ./tiles. Now, it's time to grab a coffee, this might take a while. Expect a few hours for a remote database connection with HDD's and the global dataset.
After it's all finished, the service will listen on port 5020 of your host machine, unless specified differently in docker-compose.yml.
This tutorial assumes a Ubuntu system.
Max OSX should be similar, if not the same. Windows is of course possible, but many of the commands will have to be altered.
- Python 3.6 or higher
- PostGIS installation on the host machine (solely needed for raster2pgsql)
- (Optional) Remote PostGIS installation (if you want to use a different data server)
First, customize ./openelevationservice/server/ops_settings.sample.yml and name it ops_settings.yml.
Then you can set up the environment:
cd openelevationservice
# Either via virtualenv, venv package or conda
python3.6 -m venv .venv
# or
virtualenv python=python3.6 .venv
# or
conda create -n oes python=3.6
# Activate virtual env (or equivalent conda command)
source .venv/bin/activate
# Add FLASK_APP environment variable
# For conda, see here: https://conda.io/docs/user-guide/tasks/manage-environments.html#macos-and-linux
echo "export FLASK_APP=manage" >> .venv/bin/activate
# Install required packages
pip install -r requirements.txtWhen your environment is set up, you can run the import process and start the server:
# inside the repo root directory
flask create
# rather as a background/nohup job, will download 27 GB
flask download --xyrange=0,0,73,25
flask importdata
# Start the server
flask runThe service will now listen on `http://localhost:5000.
The default base url is http://localhost:5000/.
The openelevationservice exposes 2 endpoints:
/elevation/line: used for LineString geometries/elevation/point: used for single Point geometries
| Endpoint | Method(s) allowed | Parameter | Default | Values |
|---|---|---|---|---|
/elevation/line |
POST | format_in | -- | geojson, polyline, encodedpolyline5, encodedpolyline6 |
| geometry | -- | depends on format_in |
||
| format_out | geojson | geojson, polyline, encodedpolyline5, encodedpolyline6 | ||
| dataset | srtm | srtm (so far) | ||
/elevation/point |
GET, POST | format_in | -- | geojson, point |
| geometry | -- | depends on format_in |
||
| format_out | geojson | geojson, point | ||
| dataset | srtm | srtm (so far) |
For more detailed information, please visit the API documentation.
When hosted locally, visit https://localhost:5000/apidocs.
openelevationservice recognizes the following environment variables:
| variable | function | Default | Values |
|---|---|---|---|
| OES_LOGLEVEL | Sets the level of logging output | INFO | DEBUG, INFO, WARNING, ERROR |
| APP_SETTINGS | Controls the behavior of config.py |
openelevationservice.server.config.ProductionConfig | ProductionConfig, DevelopmentConfig |
| FLASK_APP | Sets the app | manage | |
| FLASK_ENV | Development/Production server | development | production, development |
| TESTING | Sets flask testing environment | None | true |
In the case of the Docker setup, you don't need to worry about environment variables for the most part.
The flask command line interface has a few additional commands:
flask create: creates a table for CGIAR data`flask download --xyrange=0,73,0,25: downloads CGIAR data and limits the X, Y indices optionally withxyrangeflask importdata: imports CGIAR tiles it finds in./tiles/flask drop: drops CGIAR table
The testing framework is nosetests, which makes it very easy to run the tests:
TESTING=true nosetests -vcurl -XGET https://localhost:5000/elevation/point?geometry=13.349762,38.11295curl -XPOST http://localhost:5000/elevation/point \
-H 'Content-Type: application/json' \
-d '{
"format_in": "geojson",
"format_out": "geojson",
"geometry": {
"coordinates": [13.349762, 38.11295],
"type": "Point"
}
}'curl -XPOST http://localhost:5000/elevation/line \
-H 'Content-Type: application/json' \
-d '{
"format_in": "polyline",
"format_out": "encodedpolyline",
"geometry": [[13.349762, 38.11295],
[12.638397, 37.645772]]
}'