{"id":19881409,"url":"https://github.com/giscience/openelevationservice","last_synced_at":"2025-04-07T17:08:29.302Z","repository":{"id":132242551,"uuid":"154033639","full_name":"GIScience/openelevationservice","owner":"GIScience","description":":sunrise_over_mountains: A GeoJSON based service to query SRTM elevation for points/lines.","archived":false,"fork":false,"pushed_at":"2024-12-19T09:08:01.000Z","size":269,"stargazers_count":69,"open_issues_count":10,"forks_count":15,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-03-31T16:17:50.115Z","etag":null,"topics":["elevation","elevation-data","geojson","openrouteservice","srtm-data"],"latest_commit_sha":null,"homepage":"https://openrouteservice.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GIScience.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-21T17:21:22.000Z","updated_at":"2025-01-04T08:47:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"743d8868-b1ef-44bf-a6e3-e016763aba76","html_url":"https://github.com/GIScience/openelevationservice","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenelevationservice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenelevationservice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenelevationservice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenelevationservice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GIScience","download_url":"https://codeload.github.com/GIScience/openelevationservice/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694876,"owners_count":20980733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elevation","elevation-data","geojson","openrouteservice","srtm-data"],"created_at":"2024-11-12T17:14:09.370Z","updated_at":"2025-04-07T17:08:29.277Z","avatar_url":"https://github.com/GIScience.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. image:: https://travis-ci.org/GIScience/openelevationservice.svg?branch=master\n    :target: https://travis-ci.com/GIScience/openelevationservice\n    :alt: Build status\n\n.. image:: https://readthedocs.org/projects/openelevationservice/badge/?version=latest\n   :target: https://openelevationservice.readthedocs.io/en/latest/\n   :alt: Documentation Status\n\nQuickstart\n==================================================\n\nDescription\n--------------------------------------------------\n\nopenelevationservice is a Flask application which extracts elevation from various elevation datasets for `Point` or `LineString` 2D geometries and returns 3D geometries in various formats.\n\nSupported formats are:\n\n- GeoJSON\n- Polyline, i.e. list of vertices\n- Google's `encoded polyline`_\n- Point, i.e. one vertex\n\nFor 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_.\n\nFor issues and improvement suggestions, use the repo's `issue tracker`_.\n\nThis service is part of the GIScience_ software stack, crafted at `HeiGIT institute`_ at the University of Heidelberg.\n\nYou can also use our `free API`_ via (also check Endpoints_ for usage):\n\n- https://api.openrouteservice.org/elevation/point?api_key=YOUR_KEY\n- https://api.openrouteservice.org/elevation/line?api_key=YOUR_KEY\n\n.. _GIScience: https://github.com/GIScience\n.. _`HeiGIT institute`: https://heigit.org\n.. _`SRTM v4.1`: http://srtm.csi.cgiar.org\n.. _`encoded polyline`: https://developers.google.com/maps/documentation/utilities/polylinealgorithm\n.. _forum: https://ask.openrouteservice.org/c/elevation\n.. _`issue tracker`: https://github.com/GIScience/openelevationservice/issues\n.. _flasgger: https://github.com/rochacbruno/flasgger\n.. _`free API`: https://openrouteservice.org/sign-up\n\nInstallation\n----------------------------------------------------\n\nYou can either run this service on a host machine (like your PC) in a virtual environment or via docker (recommended).\n\nDocker installation\n####################################################\n\nPrerequisites\n++++++++++++++++++++++++++++++++++++++++++++++++++++\n\n- Docker\n- PostGIS installation (recommended `Kartoza's docker`_)\n\nRun Docker container\n++++++++++++++++++++++++++++++++++++++++++++++++++++\n\n1. Customize ``ops_settings_docker.sample.yml`` to your needs and name it ``ops_settings_docker.yml``\n\n2. Build container\n   ``sudo docker-compose up -d``\n\n3. Create the database\n\n.. code-block:: bash\n\n    sudo docker exec -it \u003ccontainer ID\u003e bash -c \"source /oes_venv/bin/activate; export OES_LOGLEVEL=DEBUG; flask create\"\n\n4. Download SRTM data\n\n.. code-block:: bash\n\n    sudo docker exec -it \u003ccontainer ID\u003e bash -c \"source /oes_venv/bin/activate; export OES_LOGLEVEL=DEBUG; flask download --xyrange=0,0,73,25\"\n\nThe 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`_.\n\n**Note**, that you need to have credentials to access the `FTP site`_ , which you can request here_.\n\n5. Import SRTM data\n\n.. code-block:: bash\n\n    sudo docker exec  -it \u003ccontainer ID\u003e bash -c \"source /oes_venv/bin/activate; flask importdata\"\n\nThe 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.\n\nAfter it's all finished, the service will listen on port ``5020`` of your host machine, unless specified differently in ``docker-compose.yml``.\n\n\n.. _`Kartoza's docker`: https://github.com/kartoza/docker-postgis\n.. _here: https://harvestchoice.wufoo.com/forms/download-cgiarcsi-srtm/\n.. _`FTP site`: http://data.cgiar-csi.org/srtm/tiles/GeoTIFF/\n.. _`CGIAR website`: http://srtm.csi.cgiar.org/SELECTION/inputCoord.asp\n\n\nConventional installation\n####################################################\n\nThis tutorial assumes a Ubuntu system.\n\nMax OSX should be similar, if not the same. Windows is of course possible, but many of the commands will have to be altered.\n\nPrerequisites\n++++++++++++++++++++++++++++++++++++++++++++++++++++\n\n- Python 3.6 or higher\n- PostGIS installation on the host machine (solely needed for `raster2pgsql`)\n- (Optional) Remote PostGIS installation (if you want to use a different data server)\n\nCreate virtual environment\n+++++++++++++++++++++++++++++++++++++++++++++++++++++\n\nFirst, customize ``./openelevationservice/server/ops_settings.sample.yml`` and name it ``ops_settings.yml``.\n\nThen you can set up the environment:\n\n.. code-block:: bash\n\n   cd openelevationservice\n   # Either via virtualenv, venv package or conda\n   python3.6 -m venv .venv\n   # or\n   virtualenv python=python3.6 .venv\n   # or\n   conda create -n oes python=3.6\n\n   # Activate virtual env (or equivalent conda command)\n   source .venv/bin/activate\n   # Add FLASK_APP environment variable\n   # For conda, see here: https://conda.io/docs/user-guide/tasks/manage-environments.html#macos-and-linux\n   echo \"export FLASK_APP=manage\" \u003e\u003e .venv/bin/activate\n   # Install required packages\n   pip install -r requirements.txt\n\nWhen your environment is set up, you can run the import process and start the server:\n\n.. code-block:: bash\n\n   # inside the repo root directory\n   flask create\n   # rather as a background/nohup job, will download 27 GB\n   flask download --xyrange=0,0,73,25\n   flask importdata\n\n   # Start the server\n   flask run\n\nThe service will now listen on ```http://localhost:5000``.\n\nEndpoints\n----------------------------------------------------------\n\nThe default base url is ``http://localhost:5000/``.\n\nThe openelevationservice exposes 2 endpoints:\n\n- ``/elevation/line``: used for LineString geometries\n- ``/elevation/point``: used for single Point geometries\n\n+-----------------------+-------------------+------------+---------+---------------------------------------------------------+\n|       Endpoint        | Method(s) allowed | Parameter  | Default | Values                                                  |\n+=======================+===================+============+=========+=========================================================+\n| ``/elevation/line``   | POST              | format_in  |    --   | geojson, polyline, encodedpolyline5, encodedpolyline6   |\n|                       |                   +------------+---------+---------------------------------------------------------+\n|                       |                   | geometry   |    --   | depends on ``format_in``                                |\n|                       |                   +------------+---------+---------------------------------------------------------+\n|                       |                   | format_out | geojson | geojson, polyline, encodedpolyline5, encodedpolyline6   |\n|                       |                   +------------+---------+---------------------------------------------------------+\n|                       |                   | dataset    | srtm    | srtm (so far)                                           |\n+-----------------------+-------------------+------------+---------+---------------------------------------------------------+\n| ``/elevation/point``  | GET, POST         | format_in  |    --   | geojson, point                                          |\n|                       |                   +------------+---------+---------------------------------------------------------+\n|                       |                   | geometry   |    --   | depends on ``format_in``                                |\n|                       |                   +------------+---------+---------------------------------------------------------+\n|                       |                   | format_out | geojson | geojson, point                                          |\n|                       |                   +------------+---------+---------------------------------------------------------+\n|                       |                   | dataset    | srtm    | srtm (so far)                                           |\n+-----------------------+-------------------+------------+---------+---------------------------------------------------------+\n\nFor more detailed information, please visit the `API documentation`_.\n\nWhen hosted locally, visit ``https://localhost:5000/apidocs``.\n\n.. _`API documentation`: https://openrouteservice.org/dev/#/api-docs/elevation\n\nEnvironment variables\n##########################################################\n\nopenelevationservice recognizes the following environment variables:\n\n+-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+\n|     variable    |       function                          |     Default                                           |  Values                     |\n+=================+=========================================+=======================================================+=============================+\n| OES_LOGLEVEL    | Sets the level of logging output        | INFO                                                  | DEBUG, INFO, WARNING, ERROR |\n+-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+\n| APP_SETTINGS    | Controls the behavior of ``config.py``  | openelevationservice.server.config.ProductionConfig   | ProductionConfig,           |\n|                 |                                         |                                                       |                             |\n|                 |                                         |                                                       | DevelopmentConfig           |\n+-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+\n| FLASK_APP       | Sets the app                            | manage                                                |                             |\n+-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+\n| FLASK_ENV       | Development/Production server           | development                                           | production, development     |\n+-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+\n| TESTING         | Sets flask testing environment          | None                                                  | true                        |\n+-----------------+-----------------------------------------+-------------------------------------------------------+-----------------------------+\n\nIn the case of the Docker setup, you don't need to worry about environment variables for the most part.\n\nCLI\n##########################################################\n\nThe flask command line interface has a few additional commands:\n\n-  ``flask create``: creates a table for CGIAR data\n- ```flask download --xyrange=0,73,0,25``: downloads CGIAR data and limits the X, Y indices optionally with ``xyrange``\n- ``flask importdata``: imports CGIAR tiles it finds in ``./tiles/``\n- ``flask drop``: drops CGIAR table\n\nTesting\n########################################################\n\nThe testing framework is `nosetests`, which makes it very easy to run the tests:\n\n.. code-block:: bash\n\n    TESTING=true nosetests -v\n\n\nUsage\n--------------------------------------------------------\n\nGET point\n#########################################################\n\n.. code-block:: bash\n\n  curl -XGET https://localhost:5000/elevation/point?geometry=13.349762,38.11295\n\nPOST point as GeoJSON\n#########################################################\n\n.. code-block:: bash\n\n  curl -XPOST http://localhost:5000/elevation/point \\\n    -H 'Content-Type: application/json' \\\n    -d '{\n      \"format_in\": \"geojson\",\n      \"format_out\": \"geojson\",\n      \"geometry\": {\n        \"coordinates\": [13.349762, 38.11295],\n        \"type\": \"Point\"\n      }\n    }'\n\nPOST LineString as polyline\n#########################################################\n\n.. code-block:: bash\n\n  curl -XPOST http://localhost:5000/elevation/line \\\n    -H 'Content-Type: application/json' \\\n    -d '{\n      \"format_in\": \"polyline\",\n      \"format_out\": \"encodedpolyline\",\n      \"geometry\": [[13.349762, 38.11295],\n                   [12.638397, 37.645772]]\n    }'\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiscience%2Fopenelevationservice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiscience%2Fopenelevationservice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiscience%2Fopenelevationservice/lists"}