GIScience / openelevationservice

Quickstart

Description

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

Installation

You can either run this service on a host machine (like your PC) in a virtual environment or via docker (recommended).

Docker installation

Prerequisites

• Docker
• PostGIS installation (recommended Kartoza's docker)

Run Docker container

1. Customize ops_settings_docker.sample.yml to your needs and name it ops_settings_docker.yml
2. Build container sudo docker-compose up -d
3. Create the database

sudo docker exec -it <container ID> bash -c "source /oes_venv/bin/activate; export OES_LOGLEVEL=DEBUG; flask create"

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

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

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

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

Create virtual environment

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

When 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 run

The service will now listen on `http://localhost:5000.

Endpoints

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

For more detailed information, please visit the API documentation.

When hosted locally, visit https://localhost:5000/apidocs.

Environment variables

openelevationservice recognizes the following environment variables:

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
• `flask download --xyrange=0,73,0,25: 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 table

Testing

The testing framework is nosetests, which makes it very easy to run the tests:

TESTING=true nosetests -v

Usage

GET point

curl -XGET https://localhost:5000/elevation/point?geometry=13.349762,38.11295

POST point as GeoJSON

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

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]]
  }'