{"id":19881406,"url":"https://github.com/giscience/ohsome-py","last_synced_at":"2025-10-25T12:52:18.729Z","repository":{"id":41958273,"uuid":"273236087","full_name":"GIScience/ohsome-py","owner":"GIScience","description":"Python bindings for the ohsome API","archived":false,"fork":false,"pushed_at":"2025-10-16T11:41:35.000Z","size":1810,"stargazers_count":18,"open_issues_count":9,"forks_count":4,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-10-25T12:52:15.840Z","etag":null,"topics":["ohsome","openstreetmap","openstreetmap-data","openstreetmap-history","python"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GIScience.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-06-18T12:47:13.000Z","updated_at":"2025-05-26T09:46:36.000Z","dependencies_parsed_at":"2023-11-24T18:28:13.402Z","dependency_job_id":"c9be3ff4-2e08-4373-94f2-cf4004d63ae8","html_url":"https://github.com/GIScience/ohsome-py","commit_stats":{"total_commits":122,"total_committers":6,"mean_commits":"20.333333333333332","dds":0.3770491803278688,"last_synced_commit":"5bed0c635fec4c0fc4750e6b89f4aec2ffde1226"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/GIScience/ohsome-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fohsome-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fohsome-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fohsome-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fohsome-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GIScience","download_url":"https://codeload.github.com/GIScience/ohsome-py/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fohsome-py/sbom","scorecard":{"id":53939,"data":{"date":"2025-08-11","repo":{"name":"github.com/GIScience/ohsome-py","commit":"b905821389b5b31d0eeef397bf9a14492d1f915a"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.8,"checks":[{"name":"Maintained","score":1,"reason":"2 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci-development.yml:1","Warn: no topLevel permission defined: .github/workflows/ci-production.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Code-Review","score":7,"reason":"Found 16/22 approved changesets -- score normalized to 7","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci-development.yml:8: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-development.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci-development.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-development.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci-development.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-development.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci-development.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-development.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci-development.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-development.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci-development.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-development.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci-development.yml:40: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-development.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci-production.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-production.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci-production.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-production.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci-production.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-production.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci-production.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-production.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci-production.yml:48: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-production.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci-production.yml:50: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-production.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci-production.yml:54: update your workflow using https://app.stepsecurity.io/secureworkflow/GIScience/ohsome-py/ci-production.yml/master?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/ci-development.yml:15","Info:   0 out of  10 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   4 third-party GitHubAction dependencies pinned","Info:   0 out of   1 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: GNU General Public License v3.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":2,"reason":"8 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2024-48 / GHSA-fj7x-q9j7-g6q6","Warn: Project is vulnerable to: GHSA-cpwx-vrp4-4pq7","Warn: Project is vulnerable to: GHSA-gmj6-6f8f-6699","Warn: Project is vulnerable to: GHSA-q2x7-8rv6-6q7h","Warn: Project is vulnerable to: GHSA-33p9-3p43-82vq","Warn: Project is vulnerable to: GHSA-9hjg-9r4m-mvj7","Warn: Project is vulnerable to: GHSA-48p4-8xcf-vxj5","Warn: Project is vulnerable to: GHSA-pq67-6m6q-mj2v"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 28 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-15T00:17:01.549Z","repository_id":41958273,"created_at":"2025-08-15T00:17:01.549Z","updated_at":"2025-08-15T00:17:01.549Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280958238,"owners_count":26420235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ohsome","openstreetmap","openstreetmap-data","openstreetmap-history","python"],"created_at":"2024-11-12T17:14:08.214Z","updated_at":"2025-10-25T12:52:18.677Z","avatar_url":"https://github.com/GIScience.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ohsome-py: A Python client for the ohsome API\n\n[![status: active](https://github.com/GIScience/badges/raw/master/status/active.svg)](https://github.com/GIScience/badges#active)\n\nThe *ohsome-py* package helps you extract and analyse OpenStreetMap history data using the [ohsome API](https://docs.ohsome.org/ohsome-api/v1/) and Python. It handles queries to the [ohsome API](https://docs.ohsome.org/ohsome-api/v1/) and converts its responses to [Pandas](https://pandas.pydata.org/) and [GeoPandas](https://geopandas.org/) data frames to facilitate easy data handling and analysis.\n\nThe ohsome API provides various endpoints for [data aggregation](https://api.ohsome.org/v1/swagger-ui.html?urls.primaryName=Data%20Aggregation), [data extraction](https://api.ohsome.org/v1/swagger-ui.html?urls.primaryName=dataExtraction) and [contributions](https://api.ohsome.org/v1/swagger-ui.html?urls.primaryName=Contributions) to analyse the history of OSM data. Take a look at the [documentation of the ohsome API](https://docs.ohsome.org/ohsome-api/stable) or go through the [Tutorial](https://github.com/GIScience/ohsome-py/blob/master/notebooks/Tutorial.ipynb) to get started on how to use *ohsome-py*.\n\n## Installation\n\n### Using pip\n\nYou can install *ohsome-py* using pip, which will also install all dependencies.\n\n```\n$ pip install ohsome\n```\n\n### Using Anaconda\n\n*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](pyproject.toml)) before installing *ohsome-py* using pip. Please note that there might be issues when [using pip within anaconda](https://www.anaconda.com/blog/using-pip-in-a-conda-environment). To avoid issues we advise to install everything in a new conda environment.\n\n### Dependencies for Jupyter Notebooks\n\nIf you want to run the Jupyter Notebook [Tutorial](https://github.com/GIScience/ohsome-py/blob/master/notebooks/Tutorial.ipynb) you also need to install `jupyter` and `matplotlib` e.g.\n\n```\n$ pip install jupyter matplotlib\n```\n\n## Usage\n\nAll 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.\n\n``` python\nfrom ohsome import OhsomeClient\nclient = OhsomeClient()\nclient.start_timestamp # --\u003e '2007-10-08T00:00:00Z'\nclient.end_timestamp # --\u003e '2021-01-23T03:00Z'\n```\n\n### 1. Data Aggregation\n\n**Example:** The area of OSM elements tagged as _landuse=farmland_ using the [/elements/area](https://api.ohsome.org/v1/swagger-ui.html?urls.primaryName=Data%20Aggregation#/Elements%20Area/area_1) endpoint:\n\n``` python\nresponse = client.elements.area.post(bboxes=[8.625,49.3711,8.7334,49.4397],\n\t\t\t\t      time=\"2014-01-01\",\n\t\t\t\t      filter=\"landuse=farmland and geometry:polygon\")\n```\n\nThe 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.\n\n``` python\nresponse = client.post(endpoint=\"elements/area\",\n\t\t       bboxes=[8.625,49.3711,8.7334,49.4397],\n\t\t       time=\"2020-01-01\",\n\t\t       filter=\"landuse=farmland and geometry:polygon\")\n```\n\nResponses from the data aggregation endpoints can be converted to a `pandas.DataFrame` object using the `OhsomeResponse.as_dataframe()` method.\n\n```\nresponse_df = response.as_dataframe()\n```\n\n### 2. Data Extraction\n\n**Example:** OSM elements tagged as _landuse=farmland_ including their geometry and tags using the [/elements/geometry](https://api.ohsome.org/v1/swagger-ui.html?urls.primaryName=Data%20Extraction#/Data%20Extraction/elementsGeometry_1) endpoint:\n\n``` python\nclient = OhsomeClient()\nresponse = client.elements.geometry.post(bboxes=[8.625,49.3711,8.7334,49.4397],\n\t\t\t\t\t time=\"2020-01-01\",\n\t\t\t\t\t filter=\"landuse=farmland and geometry:polygon\",\n\t\t\t\t\t properties=\"tags\")\nresponse_gdf = response.as_dataframe()\n```\n\nResponses from the data extraction endpoint can be converted to a `geopandas.GeoDataFrame`  using the `OhsomeResponse.as_dataframe()` method, since the data contains geometries.\n\n### Query Parameters\n\nAll query parameters are described in the [ohsome API documentation](https://docs.ohsome.org/ohsome-api/stable) and can be passed as `string` objects to the `post()` method. Other Python data types are accepted as well.\n\n#### Boundary\n\nThe [boundary](https://docs.ohsome.org/ohsome-api/stable/boundaries.html) of the query can be defined using the `bpolys`, `bboxes` and `bcircles` parameters. The coordinates have to be given in WGS 84 (EPSG:4326).\n\n##### bpolys\n\nThe `bpolys` parameter can be passed as a `geopandas.GeoDataFrame` containing the polygon features.\n\n``` python\nbpolys = gpd.read_file(\"./data/polygons.geojson\")\nclient.elements.count.groupByBoundary.post(bpolys=bpolys, filter=\"amenity=restaurant\")\n```\n\n##### bboxes\n\nThe `bboxes` parameter contains the coordinates of one or several bounding boxes.\n\n``` python\nbboxes = [8.7137,49.4096,8.717,49.4119] # one bounding box\nbboxes = [[8.7137,49.4096,8.717,49.4119], [8.7137,49.4096,8.717,49.4119]]\nbboxes = {\"A\": [8.67066, 49.41423, 8.68177, 49.4204],\n\t  \"B\": [8.67066, 49.41423, 8.68177, 49.4204]}\n```\n\n##### bcircles\n\nThe `bcircles` parameter contains one or several circles defined through the coordinates of the centroids and the radius in meters.\n\n```python\nbcircles = [8.7137,49.4096, 100]\nbcircles = [[8.7137,49.4096, 100], [8.7137,49.4096, 300]]\nbcircles = {\"Circle1\": [8.695, 49.41, 200],\n\t    \"Circle2\": [8.696, 49.41, 200]}\n```\n\n#### Time\n\nThe [time](https://docs.ohsome.org/ohsome-api/stable/time.html) parameter must be ISO-8601 conform can be passed in several ways\n\n```python\ntime = '2018-01-01/2018-03-01/P1M'\ntime = ['2018-01-01', '2018-02-01', '2018-03-01']\ntime = datetime.datetime(year=2018, month=3, day=1)\ntime = pandas.date_range(\"2018-01-01\", periods=3, freq=\"M\")\n```\n## Citation\n\nWhen using [ohsome-py](https://github.com/GIScience/ohsome-py) e.g. for a publication or elsewhere, please cite the ohsome-api as described in their [citation recommendation](https://github.com/GIScience/ohsome-api/blob/master/README.md#how-to-cite) for example like\n\n\u003e 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.\n\n\n```bibtex\n@software{raifer_2023_7713347,\n  author       = {Raifer, Martin and\n                  Troilo, Rafael and\n                  Mocnik, Franz-Benjamin and\n                  Schott, Moritz},\n  title        = {OSHDB - OpenStreetMap History Data Analysis version 1.2.1 accessed via the ohsome-py library version 0.3.0},\n  month        = sep,\n  year         = 2023,\n  publisher    = {Zenodo},\n  version      = {1.2.1},\n  doi          = {10.5281/zenodo.8391737},\n  url          = {https://doi.org/10.5281/zenodo.8391737}\n}\n```\n\n## Contribution Guidelines\n\nThe easiest way to contribute is to file a comprehensive [issue](https://github.com/GIScience/ohsome-py/issues) 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.\n\n### Install Package\n\nThis package uses [poetry](https://python-poetry.org/) for dependency management. To install all packages necessary for testing and development run\n\n`poetry install`\n\n### Install Pre-Commit Hooks\n\n**Install the pre-commit hooks** in our local git repo before committing to ensure homogenous code style.\n\n`poetry run pre-commit install`\n\n### Run Tests\n\n**Before pushing your commits**, run the python unit tests\n\n`poetry run pytest`\n\n#### VCR\n\nohsome-py records responses using [VCR](https://vcrpy.readthedocs.io/en/latest/) via [pytest-recording](https://github.com/kiwicom/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\n\n`poetry run pytest --record-mode=all`\n\n## References\n\nThe design of this package was inspired by the blog post [Using Python to Implement a Fluent Interface to Any REST API](https://sendgrid.com/blog/using-python-to-implement-a-fluent-interface-to-any-rest-api/) by Elmer Thomas.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiscience%2Fohsome-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiscience%2Fohsome-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiscience%2Fohsome-py/lists"}