API for analysing OpenStreetMap history data
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.10.2. Developed and maintained by HeiGIT.
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.
The following blog posts describe analyses which were using the ohsome API:
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.10.2",
"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
}
]
}
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 by HeiGIT and GIScience:
Third-Party services:
You can find a dockerized version of the ohsome API here.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
src/main/lombok
as a source directory,src/test/java
as a test-source directory,src/main/resources
as a resources directory, andtarget
, target/generated-sources/delombok
, docs/_build
, and ignite
as unmarked/excluded directories.mvn -DskipTests=true package
to build the project (if you want to build it running the integrated tests too, look at the section Testing)java -jar target/ohsome-api-1.10.2.jar --database.db=C:/path-to-your-data/ba-wue.oshdb
java -jar target/ohsome-api-1.10.2.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:
--database.multithreading=false
To run the tests locally, you need the following:
-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
mvn -Dport_get=8081 -Dport_post=8082 -Dport_data=8083 -DdbFilePathProperty="--database.db=<path-to-your-heidelberg.oshdb-file>" test
Note:
-Dintegration="no" -Djunit="no"
port_get
, port_post
, and/or port_data
properties, the respective test classes will not be executedInstall 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