Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/GIScience/ohsome-api
API for analysing OpenStreetMap history data
https://github.com/GIScience/ohsome-api
heigit ohsome openstreetmap openstreetmap-data openstreetmap-history osm osm-data
Last synced: 13 days ago
JSON representation
API for analysing OpenStreetMap history data
- Host: GitHub
- URL: https://github.com/GIScience/ohsome-api
- Owner: GIScience
- License: agpl-3.0
- Created: 2020-05-20T09:46:44.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-08-22T13:13:41.000Z (3 months ago)
- Last Synced: 2024-08-22T14:47:06.802Z (3 months ago)
- Topics: heigit, ohsome, openstreetmap, openstreetmap-data, openstreetmap-history, osm, osm-data
- Language: Java
- Homepage: https://api.ohsome.org
- Size: 3.57 MB
- Stars: 44
- Watchers: 11
- Forks: 7
- Open Issues: 57
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - GIScience/ohsome-api - API for analysing OpenStreetMap history data (others)
README
# ohsome API
[](https://jenkins.heigit.org/job/ohsome%20api/job/main/)
[](https://sonarcloud.io/dashboard?id=org.heigit.ohsome:ohsome-api)
[](https://search.maven.org/artifact/org.heigit.ohsome/ohsome-api)
[](LICENSE)
[](https://docs.ohsome.org/ohsome-api/stable)
[](https://javadoc.io/doc/org.heigit.ohsome/ohsome-api)
[](https://github.com/GIScience/badges#active)
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](https://github.com/GIScience/oshdb). The current stable version is [v1.10.4](https://github.com/GIScience/ohsome-api/releases/tag/1.10.4). Developed and maintained by [HeiGIT](https://heigit.org/).
## 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](https://heigit.org/tag/become-ohsome/), which gives diverse example analysis and updates on new features. Through the [swagger UI](https://api.ohsome.org/v1/swagger-ui.html) 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](https://heigit.org/farm-shops-are-ohsome/)
* [Visualizing the historical OSM evolution of your city](https://heigit.org/how-to-become-ohsome-part-1-visualizing-the-historical-evolution-of-osm-buildings-of-your-city/)
* [Exploring OSM history: the example of health related amenities](https://heigit.org/exploring-osm-history-the-example-of-health-related-amenities/)
* several posts of the [how to become ohsome](https://heigit.org/tag/become-ohsome/) series
Here you see an example response giving the length of residential roads for a bounding box around the German city Heidelberg.
```json
{
"attribution": {
"url": "https://ohsome.org/copyrights",
"text": "© OpenStreetMap contributors"
},
"apiVersion": "1.10.4",
"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](https://github.com/GIScience/oshdb) indirectly through the ohsome API for a publication, please cite it using the [`doi:10.5281/zenodo.4146990`](https://doi.org/10.5281/zenodo.4146990) or a corresponding version-specific DOI found on [zenodo](https://zenodo.org/record/4146990).
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`](https://doi.org/10.1186/s40965-019-0061-3).
## Services, Clients and Dockerized Version
### Services using the ohsome API
Services by [HeiGIT](https://heigit.org) and [GIScience](https://www.geog.uni-heidelberg.de/gis):
* [ohsomeHeX](https://ohsome.org/apps/osm-history-explorer/)
* [ohsome dashboard](https://ohsome.org/apps/dashboard/)
* [ohsome2label](https://github.com/GIScience/ohsome2label)
* [ohsome quality analyst](https://github.com/GIScience/ohsome-quality-analyst/)
Third-Party services:
* [is-osm-uptodate?](https://github.com/frafra/is-osm-uptodate)
### ohsome API clients
* [ohsome-py](https://github.com/GIScience/ohsome-py) - Python client
* [ohsome2x](https://www.npmjs.com/package/@giscience/ohsome2x) - nodeJS client that accepts and returns GeoJSON files and PostgreSQL/PostGIS tables
* [ohsome R](https://github.com/GIScience/ohsome-r) - R client
* [ohsome QGIS Plugin](https://github.com/GIScience/ohsome-qgis-plugin) - QGIS plugin
### ohsome API and Docker
You can find a dockerized version of the ohsome API [here](https://github.com/GIScience/ohsome-api-dockerized).
## 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 17](https://openjdk.java.net/projects/jdk/17/) or higher
* [Apache Maven 3.5](https://maven.apache.org/download.cgi) or higher
* data: [download](https://downloads.ohsome.org/OSHDB/) it directly, or work through a guide on [how to prepare a new OSHDB extract](https://github.com/GIScience/oshdb/blob/main/oshdb-etl/README.md)
### IDE Settings
* [Code style](/CONTRIBUTING.md#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](https://github.com/GIScience/oshdb/tree/main/config/ide).
* [Lombok](https://projectlombok.org/): Please check the [setup instructions](https://projectlombok.org/setup/overview) 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](#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.10.4.jar --database.db=C:/path-to-your-data/ba-wue.oshdb`
* keytables not included: `java -jar target/ohsome-api-1.10.4.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`
* 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](https://javadoc.io/doc/org.heigit.ohsome/ohsome-api), 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](https://downloads.ohsome.org/OSHDB/v1.0/europe/germany/baden-wuerttemberg/heidelberg.oshdb.mv.db) 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=" 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](https://www.sphinx-doc.org/en/master/usage/installation.html) before running the following commands e.g. by using this commands:
```bash
cd docs
pip3 install -r requirements.txt
```
To update the ohsome API swagger files for the documentation:
```bash
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:
```bash
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:
```bash
cd docs
DOCS_DEPLOYMENT=release make clean html
```
## Built With
* [Spring Boot](https://projects.spring.io/spring-boot/) - Web framework
* [Maven](https://maven.apache.org/) - Dependency management and project building
* [Sphinx](https://www.sphinx-doc.org) - API documentation