ohsome API

The ohsome API is a generic web API for in-depth analysis of OpenStreetMap (OSM) data with a focus on its history. It allows to get aggregated statistics about the evolution of OSM data itself and about the contributors behind the data. Furthermore, data extraction methods are provided to access the historic development of individual OSM features.

The functionalities of the ohsome API can be accessed via HTTP requests. As a basis underneath serves the OSHDB API. The current stable version is v1.6.3. Developed and maintained by HeiGIT.

Using the ohsome API

To make your life easier, we already have a running ohsome API instance on our servers, where you can send your requests to analyze the history of the OpenStreetMap data. This instance is publicly accessible under the following URL:

https://api.ohsome.org/v1 (current stable version)

This URL automatically redirects you to the documentation page, where you find explanations and examples for all the different parameters and endpoints that we have implemented in the API. We also have a blog post series called how to become ohsome, which gives diverse example analysis and updates on new features. Through the swagger UI page of the ohsome API you can send simple GET requests and test the individual endpoints.

If you want to contribute to the code base of the ohsome API, please follow the guideline and hints in the upcoming sections.

Examples

The following blog posts describe analyses which were using the ohsome API:

• Farm shops are ohsome
• Visualizing the historical OSM evolution of your city
• Exploring OSM history: the example of health related amenities
• several posts of the how to become ohsome series

Here you see an example response giving the length of residential roads for a bounding box around the German city Heidelberg.

{
    "attribution": {
        "url": "https://ohsome.org/copyrights",
        "text": "© OpenStreetMap contributors"
    },
    "apiVersion": "1.6.3",
    "metadata": {
        "executionTime": 858,
        "description": "Total length of items in meters.",
        "requestUrl": "http://localhost:8080/elements/length?bboxes=8.6128,49.3183,8.7294,49.4376&time=2010-01-01/2016-08-01/P2Y2M2D&showMetadata=true&filter=highway=residential%20and%20type:way"
    },
    "result": [
        {
            "timestamp": "2010-01-01T00:00:00Z",
            "value": 344220.86
        },
        {
            "timestamp": "2012-03-03T00:00:00Z",
            "value": 352116.48
        },
        {
            "timestamp": "2014-05-05T00:00:00Z",
            "value": 351579.81
        },
        {
            "timestamp": "2016-07-07T00:00:00Z",
            "value": 350577.72
        }
    ]
}

How to Cite

When using the OSHDB indirectly through the ohsome API for a publication, please cite it using the doi:10.5281/zenodo.4146990 or a corresponding version-specific DOI found on zenodo.

For scientific papers or similar publications around the analysis of OSM history data, please consider to additionally also cite the technical paper describing the OSHDB: doi:10.1186/s40965-019-0061-3.

Services, Clients and Dockerized Version

Services using the ohsome API

Services by HeiGIT and GIScience:

• ohsomeHeX
• ohsome dashboard
• ohsome2label
• ohsome quality analyst

Third-Party services:

• is-osm-uptodate?

ohsome API clients

• ohsome-py - Python client
• ohsome2x - nodeJS client that accepts and returns GeoJSON files and PostgreSQL/PostGIS tables
• ohsome R - R client
• ohsome QGIS Plugin - QGIS plugin

ohsome API and Docker

You can find a dockerized version of the ohsome API here.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

• Java 11 or higher
• Apache Maven 3.5 or higher
• data: download it directly, or work through a guide on how to prepare a new OSHDB extract

IDE Settings

• Code style: For some popular IDEs and code linting tools you can find configuration files of the used code style in the OSHDB repository: config/ide.
• Lombok: Please check the setup instructions for your IDE.
• In some cases you have to mark some directories manually by their type:
  • src/main/lombok as a source directory,
  • src/test/java as a test-source directory,
  • src/main/resources as a resources directory, and
  • target, target/generated-sources/delombok, docs/_build, and ignite as unmarked/excluded directories.

Setting-up/Running

1. checkout/download the repository
2. move to your Maven project directory in a shell (e.g. Windows PowerShell)
3. enter the command mvn -DskipTests=true package to build the project (if you want to build it running the integrated tests too, look at the section Testing)
4. to run the jar file enter the following (if no additional keytables file is given, you can assume that it is included):
   • keytables included: java -jar target/ohsome-api-1.6.3.jar --database.db=C:/path-to-your-data/ba-wue.oshdb
   • keytables not included: java -jar target/ohsome-api-1.6.3.jar --database.db=C:/path-to-your-data/ba-wue.oshdb --database.keytables=C:/path-to-your-keytablesFile/keytables

Now you should have a running local API, which is ready for receiving requests under http://localhost:8080/.
To check if it is running properly, you should be able to visit the swagger documentation under http://localhost:8080/swagger-ui.html.

Note:

• additionally you can add optional run-parameters:
  • to disable multithreading: --database.multithreading=false
  • to enable in-memory-caching: --database.caching=true (caution.. enabling this option requires quite some memory, but makes processing much faster)
• if you want to run the maven project in your IDE, you need to set the paths to your data in the run configurations
  • in Eclipse: Run As --> Run Configurations --> (x)= Arguments --> Program arguments: 'enter the parameters here'
• if you want to get information about the code directly, you can access the Javadoc, which gets updated daily.

Testing

To run the tests locally, you need the following:

1. define the properties -Dport_get -Dport_post -Dport_data using three free ports (for example 8081, 8082, 8083), which the API will use to start instances and run different integration tests
   • -Dport.get starts data-aggregation + metadata tests using GET requests
   • -Dport.post starts data-aggregation tests using POST requests
   • -Dport.data starts data-extraction tests using GET and POST requests
2. heidelberg.oshdb file (or any other, which includes the data from Heidelberg)
3. maven command: mvn -Dport_get=8081 -Dport_post=8082 -Dport_data=8083 -DdbFilePathProperty="--database.db=<path-to-your-heidelberg.oshdb-file>" test

Note:

• You can disable the integration and/or junit tests via the following properties: -Dintegration="no" -Djunit="no"
• If you do not define the port_get, port_post, and/or port_data properties, the respective test classes will not be executed

Documentation

Install Sphinx before running the following commands e.g. by using this commands:

cd docs
pip3 install -r requirements.txt

To update the ohsome API swagger files for the documentation:

cd docs
wget 'https://api.ohsome.org/v1/docs?group=Data%20Aggregation' -O _static/swagger-aggregation.json
wget 'https://api.ohsome.org/v1/docs?group=Data%20Extraction' -O _static/swagger-extraction.json
wget 'https://api.ohsome.org/v1/docs?group=Metadata' -O _static/swagger-metadata.json

The documentation can be built with the following command:

cd docs
make clean # if you want to recreate all pages
make html

If you want to see the release version of the ohsome API docs, use this environment variable:

cd docs
DOCS_DEPLOYMENT=release make clean html

Built With

• Spring Boot - Web framework
• Maven - Dependency management and project building
• Sphinx - API documentation