The ohsome-py package helps you extract and analyse OpenStreetMap history data using the ohsome API and Python. It handles queries to the ohsome API and converts its responses to Pandas and GeoPandas data frames to facilitate easy data handling and analysis.
The ohsome API provides various endpoints for data aggregation, data extraction and contributions to analyse the history of OSM data. Take a look at the documentation of the ohsome API or go through the Tutorial to get started on how to use ohsome-py.
You can install ohsome-py using pip, which will also install all dependencies.
$ pip install ohsome
ohsome-py is not available through Conda. So if you are using Conda, create a new conda environment and install your required dependencies as well as those from ohsome-py (see pyproject.toml) before installing ohsome-py using pip. Please note that there might be issues when using pip within anaconda. To avoid issues we advise to install everything in a new conda environment.
If you want to run the Jupyter Notebook Tutorial you also need to install jupyter and matplotlib e.g.
$ pip install jupyter matplotlib
All queries are handled by an OhsomeClient object, which also provides information about the current ohsome API instance, e.g. start_timestamp and end_timestamp indicate the earliest and the latest possible dates for a query.
from ohsome import OhsomeClient
client = OhsomeClient()
client.start_timestamp # --> '2007-10-08T00:00:00Z'
client.end_timestamp # --> '2021-01-23T03:00Z'Example: The area of OSM elements tagged as landuse=farmland using the /elements/area endpoint:
response = client.elements.area.post(bboxes=[8.625,49.3711,8.7334,49.4397],
time="2014-01-01",
filter="landuse=farmland and geometry:polygon")The single components of the endpoint URL are appended as method calls to the OhsomeClient object. Use automatic code completion to find valid endpoints. Alternatively, you can define the endpoint as argument in the .post() method.
response = client.post(endpoint="elements/area",
bboxes=[8.625,49.3711,8.7334,49.4397],
time="2020-01-01",
filter="landuse=farmland and geometry:polygon")Responses from the data aggregation endpoints can be converted to a pandas.DataFrame object using the OhsomeResponse.as_dataframe() method.
response_df = response.as_dataframe()
Example: OSM elements tagged as landuse=farmland including their geometry and tags using the /elements/geometry endpoint:
client = OhsomeClient()
response = client.elements.geometry.post(bboxes=[8.625,49.3711,8.7334,49.4397],
time="2020-01-01",
filter="landuse=farmland and geometry:polygon",
properties="tags")
response_gdf = response.as_dataframe()Responses from the data extraction endpoint can be converted to a geopandas.GeoDataFrame using the OhsomeResponse.as_dataframe() method, since the data contains geometries.
All query parameters are described in the ohsome API documentation and can be passed as string objects to the post() method. Other Python data types are accepted as well.
The boundary of the query can be defined using the bpolys, bboxes and bcircles parameters. The coordinates have to be given in WGS 84 (EPSG:4326).
The bpolys parameter can be passed as a geopandas.GeoDataFrame containing the polygon features.
bpolys = gpd.read_file("./data/polygons.geojson")
client.elements.count.groupByBoundary.post(bpolys=bpolys, filter="amenity=restaurant")The bboxes parameter contains the coordinates of one or several bounding boxes.
bboxes = [8.7137,49.4096,8.717,49.4119] # one bounding box
bboxes = [[8.7137,49.4096,8.717,49.4119], [8.7137,49.4096,8.717,49.4119]]
bboxes = {"A": [8.67066, 49.41423, 8.68177, 49.4204],
"B": [8.67066, 49.41423, 8.68177, 49.4204]}The bcircles parameter contains one or several circles defined through the coordinates of the centroids and the radius in meters.
bcircles = [8.7137,49.4096, 100]
bcircles = [[8.7137,49.4096, 100], [8.7137,49.4096, 300]]
bcircles = {"Circle1": [8.695, 49.41, 200],
"Circle2": [8.696, 49.41, 200]}The time parameter must be ISO-8601 conform can be passed in several ways
time = '2018-01-01/2018-03-01/P1M'
time = ['2018-01-01', '2018-02-01', '2018-03-01']
time = datetime.datetime(year=2018, month=3, day=1)
time = pandas.date_range("2018-01-01", periods=3, freq="M")When using ohsome-py e.g. for a publication or elsewhere, please cite the ohsome-api as described in their citation recommendation for example like
M. Raifer, R. Troilo, F.-B. Mocnikand M. Schott, ‘OSHDB - OpenStreetMap History Data Analysis version 1.2.1 accessed via the ohsome-py library version 0.3.0’. Zenodo, Sep. 29, 2023. doi: 10.5281/zenodo.8391737.
@software{raifer_2023_7713347,
author = {Raifer, Martin and
Troilo, Rafael and
Mocnik, Franz-Benjamin and
Schott, Moritz},
title = {OSHDB - OpenStreetMap History Data Analysis version 1.2.1 accessed via the ohsome-py library version 0.3.0},
month = sep,
year = 2023,
publisher = {Zenodo},
version = {1.2.1},
doi = {10.5281/zenodo.8391737},
url = {https://doi.org/10.5281/zenodo.8391737}
}The easiest way to contribute is to file a comprehensive issue with a reproducible example. Pull requests are always welcome, so if you want to contribute to this project, please fork the repository or create a new branch containing your changes. Follow the steps below to make sure that your contributed code follows the code style and does not break any functionality. Create a pull request to the main/master branch once it is ready to be merged.
This package uses poetry for dependency management. To install all packages necessary for testing and development run
poetry install
Install the pre-commit hooks in our local git repo before committing to ensure homogenous code style.
poetry run pre-commit install
Before pushing your commits, run the python unit tests
poetry run pytest
ohsome-py records responses using VCR via pytest-recording to prevent unnecessary network traffic and computing during testing. If you implement a test or change an existing one, make sure to update the recorded cassettes. In addition, you should delete all cassettes after a certain time (e.g. every 6m or on each new ohsome release) and re-record them. To do that run
poetry run pytest --record-mode=all
The design of this package was inspired by the blog post Using Python to Implement a Fluent Interface to Any REST API by Elmer Thomas.