:sunrise_over_mountains: A GeoJSON based service to query SRTM elevation for points/lines.
.. image:: https://travis-ci.org/GIScience/openelevationservice.svg?branch=master :target: https://travis-ci.com/GIScience/openelevationservice :alt: Build status
.. image:: https://readthedocs.org/projects/openelevationservice/badge/?version=latest :target: https://openelevationservice.readthedocs.io/en/latest/ :alt: Documentation Status
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:
encoded polyline
_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):
.. _GIScience: https://github.com/GIScience
.. _HeiGIT institute
: https://heigit.org
.. _SRTM v4.1
: http://srtm.csi.cgiar.org
.. _encoded polyline
: https://developers.google.com/maps/documentation/utilities/polylinealgorithm
.. _forum: https://ask.openrouteservice.org/c/elevation
.. _issue tracker
: https://github.com/GIScience/openelevationservice/issues
.. _flasgger: https://github.com/rochacbruno/flasgger
.. _free API
: https://openrouteservice.org/sign-up
You can either run this service on a host machine (like your PC) in a virtual environment or via docker (recommended).
Docker installation ####################################################
Prerequisites ++++++++++++++++++++++++++++++++++++++++++++++++++++
Kartoza's docker
_)Run Docker container ++++++++++++++++++++++++++++++++++++++++++++++++++++
Customize ops_settings_docker.sample.yml
to your needs and name it ops_settings_docker.yml
Build container
sudo docker-compose up -d
Create the database
.. code-block:: bash
sudo docker exec -it <container ID> bash -c "source /oes_venv/bin/activate; export OES_LOGLEVEL=DEBUG; flask create"
.. code-block:: bash
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_.
.. code-block:: bash
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
.
.. _Kartoza's docker
: https://github.com/kartoza/docker-postgis
.. _here: https://harvestchoice.wufoo.com/forms/download-cgiarcsi-srtm/
.. _FTP site
: http://data.cgiar-csi.org/srtm/tiles/GeoTIFF/
.. _CGIAR website
: http://srtm.csi.cgiar.org/SELECTION/inputCoord.asp
Conventional installation ####################################################
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.
Prerequisites ++++++++++++++++++++++++++++++++++++++++++++++++++++
raster2pgsql
)Create virtual environment +++++++++++++++++++++++++++++++++++++++++++++++++++++
First, customize ./openelevationservice/server/ops_settings.sample.yml
and name it ops_settings.yml
.
Then you can set up the environment:
.. code-block:: bash
cd openelevationservice
python3.6 -m venv .venv
virtualenv python=python3.6 .venv
conda create -n oes python=3.6
source .venv/bin/activate
echo "export FLASK_APP=manage" >> .venv/bin/activate
pip install -r requirements.txt
When your environment is set up, you can run the import process and start the server:
.. code-block:: bash
flask create
flask download --xyrange=0,0,73,25 flask importdata
flask run
The 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
.
.. _API documentation
: https://coming.soon
Environment variables ##########################################################
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.
CLI ##########################################################
The flask command line interface has a few additional commands:
flask create
: creates a table for CGIAR data: downloads CGIAR data and limits the X, Y indices optionally with
xyrange``flask importdata
: imports CGIAR tiles it finds in ./tiles/
flask drop
: drops CGIAR tableTesting ########################################################
The testing framework is nosetests
, which makes it very easy to run the tests:
.. code-block:: bash
TESTING=true nosetests -v
GET point #########################################################
.. code-block:: bash
curl -XGET https://localhost:5000/elevation/point?geometry=13.349762,38.11295
POST point as GeoJSON #########################################################
.. code-block:: bash
curl -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"
}
}'
POST LineString as polyline #########################################################
.. code-block:: bash
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]]
}'