Package: ohsome
ohsome-py: A Python client for the ohsome APITheohsome-pypackage helps you extract and analyse OpenStreetMap history data using theohsome APIand Python. It handles queries to theohsome APIand converts its responses toPandasandGeoPandasdata frames to facilitate easy data handling and analysis.The ohsome API provides various endpoints fordata aggregation,data extractionandcontributionsto analyse the history of OSM data. Take a look at thedocumentation of the ohsome APIor go through theTutorialto get started on how to useohsome-py.InstallationUsing pipYou can installohsome-pyusing pip, which will also install all dependencies.$ pip install ohsomeUsing Anacondaohsome-pyis not available through Conda. So if you are using Conda, create a new conda environment and install your required dependencies as well as those fromohsome-py(seepyproject.toml) before installingohsome-pyusing pip. Please note that there might be issues whenusing pip within anaconda. To avoid issues we advise to install everything in a new conda environment.Dependencies for Jupyter NotebooksIf you want to run the Jupyter NotebookTutorialyou also need to installjupyterandmatplotlibe.g.$ pip install jupyter matplotlibUsageAll queries are handled by anOhsomeClientobject, which also provides information about the current ohsome API instance, e.g.start_timestampandend_timestampindicate the earliest and the latest possible dates for a query.fromohsomeimportOhsomeClientclient=OhsomeClient()client.start_timestamp# --> '2007-10-08T00:00:00Z'client.end_timestamp# --> '2021-01-23T03:00Z'1. Data AggregationExample:The area of OSM elements tagged aslanduse=farmlandusing the/elements/areaendpoint: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 theOhsomeClientobject. 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 apandas.DataFrameobject using theOhsomeResponse.as_dataframe()method.response_df = response.as_dataframe()2. Data ExtractionExample:OSM elements tagged aslanduse=farmlandincluding their geometry and tags using the/elements/geometryendpoint: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 ageopandas.GeoDataFrameusing theOhsomeResponse.as_dataframe()method, since the data contains geometries.Query ParametersAll query parameters are described in theohsome API documentationand can be passed asstringobjects to thepost()method. Other Python data types are accepted as well.BoundaryTheboundaryof the query can be defined using thebpolys,bboxesandbcirclesparameters. The coordinates have to be given in WGS 84 (EPSG:4326).bpolysThebpolysparameter can be passed as ageopandas.GeoDataFramecontaining the polygon features.bpolys=gpd.read_file("./data/polygons.geojson")client.elements.count.groupByBoundary.post(bpolys=bpolys,filter="amenity=restaurant")bboxesThebboxesparameter contains the coordinates of one or several bounding boxes.bboxes=[8.7137,49.4096,8.717,49.4119]# one bounding boxbboxes=[[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]}bcirclesThebcirclesparameter 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]}TimeThetimeparameter must be ISO-8601 conform can be passed in several waystime='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")CitationWhen usingohsome-pye.g. for a publication or elsewhere, please cite the ohsome-api as described in theircitation recommendationfor example likeM. 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 andTroilo, Rafael andMocnik, Franz-Benjamin andSchott, 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}}Contribution GuidelinesThe easiest way to contribute is to file a comprehensiveissuewith 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 apull request to the main/masterbranch once it is ready to be merged.Install PackageThis package usespoetryfor dependency management. To install all packages necessary for testing and development runpoetry installInstall Pre-Commit HooksInstall the pre-commit hooksin our local git repo before committing to ensure homogenous code style.poetry run pre-commit installRun TestsBefore pushing your commits, run the python unit testspoetry run pytestVCRohsome-py records responses usingVCRviapytest-recordingto 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 runpoetry run pytest --record-mode=allReferencesThe design of this package was inspired by the blog postUsing Python to Implement a Fluent Interface to Any REST APIby Elmer Thomas.