overturemaps 1.0.2__tar.gz → 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. {overturemaps-1.0.2 → overturemaps-2.0.0}/.github/dependabot.yml +4 -4
  2. {overturemaps-1.0.2 → overturemaps-2.0.0}/.github/workflows/build-binaries.yml +17 -3
  3. {overturemaps-1.0.2 → overturemaps-2.0.0}/.github/workflows/publish-pypi.yml +27 -4
  4. overturemaps-2.0.0/.github/workflows/release.yml +71 -0
  5. {overturemaps-1.0.2 → overturemaps-2.0.0}/.github/workflows/test-run.yml +3 -3
  6. overturemaps-2.0.0/CONTRIBUTING.md +68 -0
  7. overturemaps-2.0.0/PKG-INFO +91 -0
  8. overturemaps-2.0.0/README.md +66 -0
  9. {overturemaps-1.0.2 → overturemaps-2.0.0}/SPEC.md +13 -12
  10. overturemaps-2.0.0/docs/cli.md +70 -0
  11. overturemaps-2.0.0/docs/performance.md +16 -0
  12. overturemaps-2.0.0/docs/python-api.md +49 -0
  13. overturemaps-2.0.0/docs/screenshot.png +0 -0
  14. overturemaps-2.0.0/overturemaps/_http.py +23 -0
  15. {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/changelog.py +2 -2
  16. {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/core.py +3 -3
  17. {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/models.py +1 -16
  18. {overturemaps-1.0.2 → overturemaps-2.0.0}/pyproject.toml +15 -2
  19. overturemaps-2.0.0/tests/test_http.py +56 -0
  20. overturemaps-2.0.0/uv.lock +1537 -0
  21. overturemaps-1.0.2/CONTRIBUTING.md +0 -53
  22. overturemaps-1.0.2/PKG-INFO +0 -190
  23. overturemaps-1.0.2/README.md +0 -165
  24. overturemaps-1.0.2/uv.lock +0 -1040
  25. {overturemaps-1.0.2 → overturemaps-2.0.0}/.gitignore +0 -0
  26. {overturemaps-1.0.2 → overturemaps-2.0.0}/CODEOWNERS +0 -0
  27. {overturemaps-1.0.2 → overturemaps-2.0.0}/LICENSE +0 -0
  28. {overturemaps-1.0.2 → overturemaps-2.0.0}/benchmarks/bench_count_rows.py +0 -0
  29. {overturemaps-1.0.2 → overturemaps-2.0.0}/benchmarks/bench_geojson_writer.py +0 -0
  30. {overturemaps-1.0.2 → overturemaps-2.0.0}/justfile +0 -0
  31. {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/__init__.py +0 -0
  32. {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/__main__.py +0 -0
  33. {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/cli.py +0 -0
  34. {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/examples/geopandas_example.ipynb +0 -0
  35. {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/releases.py +0 -0
  36. {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/state.py +0 -0
  37. {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/writers.py +0 -0
  38. {overturemaps-1.0.2 → overturemaps-2.0.0}/pytest.ini +0 -0
  39. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/__init__.py +0 -0
  40. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_changelog.py +0 -0
  41. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_cli_download.py +0 -0
  42. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_cli_gers.py +0 -0
  43. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_cli_releases.py +0 -0
  44. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_copy.py +0 -0
  45. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_core.py +0 -0
  46. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_gers.py +0 -0
  47. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_main.py +0 -0
  48. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_models.py +0 -0
  49. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_releases.py +0 -0
  50. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_state.py +0 -0
  51. {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_writers.py +0 -0
@@ -15,13 +15,13 @@ updates:
15
15
  labels:
16
16
  - "bot"
17
17
  commit-message:
18
- prefix: "[CHORE](deps)"
18
+ prefix: "chore"
19
19
  include: "scope"
20
20
  cooldown:
21
21
  default-days: 7
22
22
 
23
- # Maintain Python dependencies
24
- - package-ecosystem: "pip"
23
+ # Maintain Python dependencies (pyproject.toml and uv.lock)
24
+ - package-ecosystem: "uv"
25
25
  directory: "/"
26
26
  schedule:
27
27
  interval: "weekly"
@@ -33,7 +33,7 @@ updates:
33
33
  labels:
34
34
  - "bot"
35
35
  commit-message:
36
- prefix: "[CHORE](deps)"
36
+ prefix: "chore"
37
37
  include: "scope"
38
38
  cooldown:
39
39
  default-days: 7
@@ -44,12 +44,26 @@ jobs:
44
44
  persist-credentials: false
45
45
 
46
46
  - name: Install uv
47
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
47
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
48
48
  with:
49
49
  enable-cache: false
50
50
 
51
+ - name: Stamp version
52
+ id: stamp
53
+ shell: bash
54
+ env:
55
+ TAG: ${{ github.event.release.tag_name }}
56
+ run: |
57
+ if [ "$GITHUB_EVENT_NAME" = "release" ]; then
58
+ version="${TAG#v}"
59
+ else
60
+ version="0.0.0.dev${GITHUB_RUN_ID}${GITHUB_RUN_ATTEMPT}"
61
+ fi
62
+ uv version "$version" --frozen
63
+ echo "version=$version" >> "$GITHUB_OUTPUT"
64
+
51
65
  - name: Install dependencies
52
- run: uv sync --group binary
66
+ run: uv sync --group binary --frozen
53
67
 
54
68
  - name: Get version
55
69
  id: version
@@ -95,7 +109,7 @@ jobs:
95
109
 
96
110
  - name: Upload artifact (dry run)
97
111
  if: github.event_name == 'workflow_dispatch'
98
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
112
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
99
113
  with:
100
114
  name: overturemaps-${{ matrix.target }}
101
115
  path: ${{ env.BINARY_PATH }}
@@ -30,15 +30,38 @@ jobs:
30
30
  persist-credentials: false
31
31
 
32
32
  - name: Install uv
33
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
33
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
34
34
  with:
35
35
  enable-cache: false
36
36
 
37
+ - name: Stamp version
38
+ id: stamp
39
+ env:
40
+ TAG: ${{ github.event.release.tag_name }}
41
+ run: |
42
+ if [ "$GITHUB_EVENT_NAME" = "release" ]; then
43
+ version="${TAG#v}"
44
+ else
45
+ version="0.0.0.dev${GITHUB_RUN_ID}${GITHUB_RUN_ATTEMPT}"
46
+ fi
47
+ uv version "$version" --frozen
48
+ echo "version=$version" >> "$GITHUB_OUTPUT"
49
+
37
50
  - name: Build package
38
51
  run: uv build
39
52
 
53
+ - name: Check package metadata
54
+ run: uvx twine check --strict dist/*
55
+
56
+ - name: Check built versions
57
+ env:
58
+ EXPECTED_VERSION: ${{ steps.stamp.outputs.version }}
59
+ run: |
60
+ test -f "dist/overturemaps-${EXPECTED_VERSION}-py3-none-any.whl"
61
+ test -f "dist/overturemaps-${EXPECTED_VERSION}.tar.gz"
62
+
40
63
  - name: Upload dist artifacts
41
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
64
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
42
65
  with:
43
66
  name: dist
44
67
  path: dist/
@@ -54,13 +77,13 @@ jobs:
54
77
  id-token: write # OIDC — required for PyPI trusted publishing
55
78
  steps:
56
79
  - name: Download dist artifacts
57
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
80
+ uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
58
81
  with:
59
82
  name: dist
60
83
  path: dist/
61
84
 
62
85
  - name: Publish
63
- uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
86
+ uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
64
87
  with:
65
88
  repository-url: ${{ github.event_name == 'workflow_dispatch' && env.TEST_PYPI_URL || '' }}
66
89
  skip-existing: ${{ github.event_name == 'workflow_dispatch' }} # Don't fail on version conflicts during test-publishing
@@ -0,0 +1,71 @@
1
+ # Cuts a GitHub Release from Conventional Commits on every push to main.
2
+ # Nothing is committed back to main; release notes are generated on the GitHub Release.
3
+ #
4
+ # The release is created with the overture-releaser GitHub App's token, not GITHUB_TOKEN:
5
+ # GITHUB_TOKEN-created releases don't fire `release: published`.
6
+ name: Release
7
+
8
+ on:
9
+ push:
10
+ branches:
11
+ - main
12
+
13
+ permissions: {}
14
+
15
+ concurrency:
16
+ group: ${{ github.workflow }}
17
+ cancel-in-progress: false
18
+
19
+ jobs:
20
+ release:
21
+ name: Create release
22
+ if: github.repository == 'OvertureMaps/overturemaps-py'
23
+ runs-on: ubuntu-latest
24
+ permissions:
25
+ contents: read
26
+ id-token: write # OIDC access to the AWS role that reads the releaser app PEM
27
+ steps:
28
+ - name: Checkout code
29
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
30
+ with:
31
+ fetch-depth: 0
32
+ persist-credentials: false
33
+
34
+ - name: Install uv
35
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
36
+ with:
37
+ enable-cache: false
38
+
39
+ - name: Configure AWS credentials
40
+ uses: aws-actions/configure-aws-credentials@e1253824e5c10ff9df46874f81ed3ec929e19cfd # v6.3.0
41
+ with:
42
+ aws-region: us-west-2
43
+ role-to-assume: arn:aws:iam::816069134238:role/gha-releaser-secrets-reader
44
+ role-session-name: GitHubActions_${{ github.job }}_${{ github.run_id }}
45
+
46
+ - name: Fetch releaser PEM from Secrets Manager
47
+ uses: aws-actions/aws-secretsmanager-get-secrets@2297f9a879480a9e3af9b293ed15c70caf8e1c88 # v3.0.2
48
+ with:
49
+ secret-ids: |
50
+ RELEASER_APP_PEM, omf-github-terraform/releaser/pem
51
+
52
+ - name: Generate app token
53
+ id: app-token
54
+ uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
55
+ with:
56
+ client-id: Iv23lijru2e660v1zJQO # overture-releaser app ID, not sensitive
57
+ private-key: ${{ env.RELEASER_APP_PEM }} # zizmor: ignore[secrets-outside-env]
58
+ permission-contents: write
59
+
60
+ - name: Create release
61
+ env:
62
+ GH_TOKEN: ${{ steps.app-token.outputs.token }}
63
+ run: |
64
+ version=$(uv run --only-group release semantic-release version --print)
65
+ tag="v${version}"
66
+ if git rev-parse --verify --quiet "refs/tags/${tag}" >/dev/null; then
67
+ echo "${tag} already exists; no releasable commits."
68
+ exit 0
69
+ fi
70
+ gh release create "${tag}" --repo "${GITHUB_REPOSITORY}" --target "${GITHUB_SHA}" \
71
+ --title "${tag}" --generate-notes
@@ -21,14 +21,14 @@ jobs:
21
21
  contents: read
22
22
  strategy:
23
23
  matrix:
24
- python-version: ["3.10", "3.11", "3.12", "3.13"]
24
+ python-version: ["3.11", "3.12", "3.13", "3.14"]
25
25
  steps:
26
26
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
27
27
  with:
28
28
  persist-credentials: false
29
29
 
30
30
  - name: Install uv
31
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
31
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
32
32
  with:
33
33
  enable-cache: true
34
34
  python-version: ${{ matrix.python-version }}
@@ -52,6 +52,6 @@ jobs:
52
52
  runs-on: ubuntu-latest
53
53
  permissions: {}
54
54
  steps:
55
- - uses: lowlydba/are-we-good@f506ed6324f55ec5e4ff5d92204a72c7f1c2b4f8 # v1.0.5
55
+ - uses: lowlydba/are-we-good@6b10e5f2697555fbaf7f8f37ce38d4454c954a4c # v1.2.2
56
56
  with:
57
57
  jobs: ${{ toJSON(needs) }}
@@ -0,0 +1,68 @@
1
+ # Contributing
2
+
3
+ ## Publishing
4
+
5
+ ### Overview
6
+
7
+ The package is published to [PyPI](https://pypi.org/project/overturemaps/) via the
8
+ [`publish-pypi.yml`](.github/workflows/publish-pypi.yml) GitHub Actions workflow using
9
+ [OIDC trusted publishing](https://docs.pypi.org/trusted-publishers/), no API token should be used. This repo, workflow, and GitHub environment have been pre-configured in PyPI and Test PyPI for publishing.
10
+
11
+ ### Releasing a new version
12
+
13
+ Releases run automatically on every push to `main`. Do not edit `project.version` by hand; it is a
14
+ `0.0.0` placeholder. The publish and binary workflows stamp the release tag's version into the
15
+ build without committing it. The squash-merged PR title drives the next version, so PRs must use
16
+ [Conventional Commits](https://www.conventionalcommits.org/):
17
+
18
+ - `fix:` and `perf:` release a patch; `feat:` releases a minor version.
19
+ - Add `!` or a `BREAKING CHANGE:` footer for a major version.
20
+ - `docs:`, `chore:`, `ci:`, `test:`, and `build:` do not trigger a release.
21
+
22
+ This repository uses squash merges so the PR title is the commit message read by the release
23
+ workflow. Release notes are published on the GitHub Release; no version commit or `CHANGELOG.md`
24
+ is written back to `main`.
25
+
26
+ Publishing a GitHub Release triggers the following:
27
+
28
+ - The publish-pypi workflow builds the package and publishes to PyPI in the
29
+ [`pypi` GitHub environment](https://github.com/OvertureMaps/overturemaps-py/deployments).
30
+ - The build-binaries workflow builds cross-OS binaries and attaches them to the release.
31
+ - `brew`'s BrewTestBot scans PyPI every 3 hours and updates our
32
+ [Homebrew formula](https://github.com/Homebrew/homebrew-core/blob/main/Formula/o/overturemaps.rb).
33
+
34
+ ### Dry-run / Test PyPI
35
+
36
+ Trigger `publish-pypi.yml` manually to publish to
37
+ [Test PyPI](https://test.pypi.org/project/overturemaps/) instead of production PyPI. This is useful
38
+ for verifying the build and publish pipeline without affecting the real package index. Manual runs
39
+ stamp a unique `0.0.0.dev<run_id><attempt>` version. The workflow uses `skip-existing: true` for test
40
+ publishes so version conflicts do not fail the run. Manually trigger `build-binaries.yml` to inspect
41
+ binary artifacts with the same development version format without attaching them to a release.
42
+
43
+ ### Environments
44
+
45
+ | GitHub environment | Target index | Trigger |
46
+ |--------------------|--------------|---------|
47
+ | `pypi` | PyPI (production) | GitHub Release published |
48
+ | `test-pypi` | Test PyPI | Manual `workflow_dispatch` |
49
+
50
+ Both environments are configured with OIDC trusted publisher entries on their respective package
51
+ indexes; no secrets or API tokens are stored in the repository.
52
+
53
+ ## Testing
54
+
55
+ Tests run on pull requests and pushes to `main` via [`test-run.yml`](.github/workflows/test-run.yml).
56
+
57
+ To run tests locally:
58
+
59
+ ```bash
60
+ uv sync --dev
61
+ uv run pytest tests/ -v
62
+ ```
63
+
64
+ A CLI smoke test is also included in CI:
65
+
66
+ ```bash
67
+ uv run overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=building -o boston.geojson
68
+ ```
@@ -0,0 +1,91 @@
1
+ Metadata-Version: 2.5
2
+ Name: overturemaps
3
+ Version: 2.0.0
4
+ Summary: Python tools for interacting with Overture Maps (overturemaps.org) data.
5
+ Project-URL: Homepage, https://overturemaps.org
6
+ Project-URL: Source, https://github.com/OvertureMaps/overturemaps-py
7
+ Project-URL: Issues, https://github.com/OvertureMaps/overturemaps-py/issues
8
+ Author-email: Jacob Wasserman <jwasserman@meta.com>
9
+ Maintainer-email: Adam Lastowka <adam@overturemaps.org>, Dana Bauer <dana@overturemaps.org>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: GIS,geojson,geospatial,mapping,maps,opendata,overture,parquet,shapely
13
+ Requires-Python: >=3.11
14
+ Requires-Dist: click>=8.3.0
15
+ Requires-Dist: colorama>=0.4.6
16
+ Requires-Dist: numpy>=1.26.4
17
+ Requires-Dist: orjson>=3.9.0
18
+ Requires-Dist: pyarrow>=15.0.2
19
+ Requires-Dist: pyfiglet>=1.0.2
20
+ Requires-Dist: shapely>=2.1.0
21
+ Requires-Dist: tqdm>=4.67.3
22
+ Provides-Extra: geopandas
23
+ Requires-Dist: geopandas>=1.1.0; extra == 'geopandas'
24
+ Description-Content-Type: text/markdown
25
+
26
+ [![PyPI](https://img.shields.io/pypi/v/overturemaps.svg)](https://pypi.org/project/overturemaps/)
27
+ [![conda-forge](https://img.shields.io/conda/vn/conda-forge/overturemaps.svg)](https://anaconda.org/conda-forge/overturemaps)
28
+ [![Homebrew](https://img.shields.io/badge/Homebrew-overturemaps-FBB040?logo=homebrew)](https://formulae.brew.sh/formula/overturemaps)
29
+ [![Standalone Binaries](https://img.shields.io/badge/binaries-Linux%20%7C%20macOS%20%7C%20Windows-2ea44f)](https://github.com/OvertureMaps/overturemaps-py/releases/latest)
30
+ [![GitHub Release](https://img.shields.io/github/v/release/OvertureMaps/overturemaps-py?display_name=release)](https://github.com/OvertureMaps/overturemaps-py/releases/latest)
31
+
32
+ # overturemaps-py
33
+
34
+ <p align="center">
35
+ <img src="docs/screenshot.png" alt="overturemaps cli screenshot" width="800">
36
+ </p>
37
+
38
+ Official Python command-line tool of the [Overture Maps Foundation](https://overturemaps.org).
39
+
40
+ Overture provides free and open geospatial map data, from many different sources and normalized to a
41
+ [common schema](https://github.com/OvertureMaps/schema). This tool helps to download Overture data
42
+ within a region of interest and converts it to a few different file formats. For more information about accessing
43
+ Overture data, see the [official documentation site](https://docs.overturemaps.org).
44
+
45
+ ## Installation
46
+
47
+ Install with pip:
48
+
49
+ ```bash
50
+ pip install overturemaps
51
+ ```
52
+
53
+ Also available via:
54
+
55
+ ```bash
56
+ # Homebrew
57
+ brew install overturemaps
58
+
59
+ # conda-forge
60
+ conda install -c conda-forge overturemaps
61
+
62
+ # uvx
63
+ uvx overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston.parquet
64
+ ```
65
+
66
+
67
+ ## Quick Start
68
+
69
+ Download building footprints for a bounding box as GeoParquet:
70
+
71
+ ```bash
72
+ overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston.parquet
73
+ ```
74
+
75
+ ## Commands
76
+
77
+ The CLI includes these top-level commands:
78
+
79
+ - `download`: download Overture data, optionally clipped to a bounding box.
80
+ - `gers`: look up a single feature by GERS ID.
81
+ - `releases`: inspect available Overture releases.
82
+ - `changelog`: query GERS feature changes across releases.
83
+
84
+ Run `overturemaps --help` for the full command tree.
85
+
86
+ ## Documentation
87
+
88
+ - [CLI guide](docs/cli.md)
89
+ - [Python API guide](docs/python-api.md)
90
+ - [Performance notes](docs/performance.md)
91
+ - [Contributing guide](CONTRIBUTING.md)
@@ -0,0 +1,66 @@
1
+ [![PyPI](https://img.shields.io/pypi/v/overturemaps.svg)](https://pypi.org/project/overturemaps/)
2
+ [![conda-forge](https://img.shields.io/conda/vn/conda-forge/overturemaps.svg)](https://anaconda.org/conda-forge/overturemaps)
3
+ [![Homebrew](https://img.shields.io/badge/Homebrew-overturemaps-FBB040?logo=homebrew)](https://formulae.brew.sh/formula/overturemaps)
4
+ [![Standalone Binaries](https://img.shields.io/badge/binaries-Linux%20%7C%20macOS%20%7C%20Windows-2ea44f)](https://github.com/OvertureMaps/overturemaps-py/releases/latest)
5
+ [![GitHub Release](https://img.shields.io/github/v/release/OvertureMaps/overturemaps-py?display_name=release)](https://github.com/OvertureMaps/overturemaps-py/releases/latest)
6
+
7
+ # overturemaps-py
8
+
9
+ <p align="center">
10
+ <img src="docs/screenshot.png" alt="overturemaps cli screenshot" width="800">
11
+ </p>
12
+
13
+ Official Python command-line tool of the [Overture Maps Foundation](https://overturemaps.org).
14
+
15
+ Overture provides free and open geospatial map data, from many different sources and normalized to a
16
+ [common schema](https://github.com/OvertureMaps/schema). This tool helps to download Overture data
17
+ within a region of interest and converts it to a few different file formats. For more information about accessing
18
+ Overture data, see the [official documentation site](https://docs.overturemaps.org).
19
+
20
+ ## Installation
21
+
22
+ Install with pip:
23
+
24
+ ```bash
25
+ pip install overturemaps
26
+ ```
27
+
28
+ Also available via:
29
+
30
+ ```bash
31
+ # Homebrew
32
+ brew install overturemaps
33
+
34
+ # conda-forge
35
+ conda install -c conda-forge overturemaps
36
+
37
+ # uvx
38
+ uvx overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston.parquet
39
+ ```
40
+
41
+
42
+ ## Quick Start
43
+
44
+ Download building footprints for a bounding box as GeoParquet:
45
+
46
+ ```bash
47
+ overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston.parquet
48
+ ```
49
+
50
+ ## Commands
51
+
52
+ The CLI includes these top-level commands:
53
+
54
+ - `download`: download Overture data, optionally clipped to a bounding box.
55
+ - `gers`: look up a single feature by GERS ID.
56
+ - `releases`: inspect available Overture releases.
57
+ - `changelog`: query GERS feature changes across releases.
58
+
59
+ Run `overturemaps --help` for the full command tree.
60
+
61
+ ## Documentation
62
+
63
+ - [CLI guide](docs/cli.md)
64
+ - [Python API guide](docs/python-api.md)
65
+ - [Performance notes](docs/performance.md)
66
+ - [Contributing guide](CONTRIBUTING.md)
@@ -1,7 +1,7 @@
1
1
  # overturemaps-py — Project Specification
2
2
 
3
3
  **Version**: 0.21.0
4
- **Python**: ≥ 3.10
4
+ **Python**: ≥ 3.11
5
5
  **License**: MIT
6
6
  **Maintainers**: Adam Lastowka, Dana Bauer (@overturemaps.org)
7
7
 
@@ -103,7 +103,7 @@ Serialization: `as_tuple()`, `as_dict()`, `from_dict()`.
103
103
 
104
104
  Values: `geojson`, `geojsonseq`, `geoparquet`.
105
105
 
106
- Python 3.10 compatible (StrEnum added in 3.11; shim required).
106
+ Uses `enum.StrEnum` (Python ≥ 3.11).
107
107
 
108
108
  ### 3.4 `PipelineState` Dataclass
109
109
 
@@ -404,8 +404,8 @@ State file path = `{output_path}.state` (e.g. `boston.geojson.state`).
404
404
 
405
405
  ### 10.4 Compatibility
406
406
 
407
- - **Python**: 3.10, 3.11, 3.12, 3.13 (tested in CI matrix).
408
- - **StrEnum shim**: Python 3.10 compat required; do not use `enum.StrEnum` directly.
407
+ - **Python**: 3.11, 3.12, 3.13, 3.14 (tested in CI matrix).
408
+ - **StrEnum**: use stdlib `enum.StrEnum`.
409
409
  - **geopandas**: Optional extra. Library must import and function without it. `HAS_GEOPANDAS` flag gates all geopandas usage. Stub `GeoDataFrame` class prevents `NameError` at import time.
410
410
 
411
411
  ### 10.5 Observability
@@ -490,7 +490,7 @@ State file path = `{output_path}.state` (e.g. `boston.geojson.state`).
490
490
  ### 13.1 Test workflow
491
491
 
492
492
  - Triggers: push to `main`, PR to `main`.
493
- - Matrix: Python 3.10, 3.11, 3.12, 3.13.
493
+ - Matrix: Python 3.11, 3.12, 3.13, 3.14.
494
494
  - Steps: checkout → setup-uv (with cache) → `uv sync --dev` → `pytest tests/ -v` → CLI smoke test.
495
495
  - Smoke test: Boston buildings download to file, format `geojson`.
496
496
  - Rollup job `are-we-good` must always run; blocks merge on any matrix failure.
@@ -532,7 +532,7 @@ State file path = `{output_path}.state` (e.g. `boston.geojson.state`).
532
532
  - **Type annotations**: all public API functions should have full type annotations. Internal helpers may be unannotated where obvious.
533
533
  - **Docstrings**: not required by convention. Add only where behavior is non-obvious (e.g. STAC fallback design, binary search invariants).
534
534
  - **No mutable default arguments**.
535
- - **StrEnum shim** must be tested for Python 3.10 behavior.
535
+ - **StrEnum** string behavior (`str()`, lowercase auto values) must be tested.
536
536
 
537
537
  ### 14.2 Error handling principles
538
538
 
@@ -559,13 +559,14 @@ State file path = `{output_path}.state` (e.g. `boston.geojson.state`).
559
559
 
560
560
  - **Build backend**: `hatchling`
561
561
  - **Package manager / task runner**: `uv` + `just`
562
- - **Version source**: `pyproject.toml` `version` field (not dynamic)
563
- - **Release cadence**: Tracks Overture Maps data releases (approximately monthly)
562
+ - **Version source**: Release tag stamped into `project.version` at build time; committed version is a `0.0.0` placeholder
563
+ - **Release cadence**: Automatic on pushes to `main` when Conventional Commit titles require a bump
564
564
  - **PyPI package name**: `overturemaps`
565
565
  - **Standalone binaries**: Built via PyInstaller on release; attached to GitHub Release as assets for linux-x86_64, macos-arm64, macos-x86_64, windows-x86_64. Local build: `just build-binary`.
566
566
  - **`python -m overturemaps`**: Supported via `overturemaps/__main__.py`; same entry point used by PyInstaller.
567
567
 
568
- Version bump checklist:
569
- 1. Update `version` in `pyproject.toml`.
570
- 2. Create GitHub release with matching tag.
571
- 3. Publish workflow auto-triggers on release event.
568
+ Squash-merged PR titles use Conventional Commits to choose the next version. The release workflow
569
+ creates a GitHub Release with generated notes. Publishing that release triggers the PyPI and binary
570
+ workflows; Homebrew updates from PyPI. Manual builds use a unique `0.0.0.dev<run_id><attempt>`
571
+ version. The publishing workflow checks both distribution metadata and version consistency before
572
+ uploading artifacts.
@@ -0,0 +1,70 @@
1
+ # CLI guide
2
+
3
+ `overturemaps` downloads Overture data directly from Overture's S3 bucket and exposes a small set of commands for common data access tasks.
4
+
5
+ ## Commands
6
+
7
+ - `download`: download Overture data, optionally clipped to a bounding box.
8
+ - `gers`: look up a single feature by GERS ID.
9
+ - `releases`: inspect available Overture releases.
10
+ - `changelog`: query GERS feature changes across releases.
11
+
12
+ Run `overturemaps --help` for the top-level command tree.
13
+
14
+ ## download
15
+
16
+ `download` streams Overture data in the requested output format. When you provide a bounding box, the Parquet readers use summary statistics to minimize transferred data.
17
+
18
+ ```bash
19
+ overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=building -o boston.geojson
20
+ ```
21
+
22
+ Options:
23
+
24
+ - `--bbox`: west, south, east, north longitude and latitude coordinates. When omitted, the entire dataset for the specified type is downloaded.
25
+ - `-f`: required output format. Supported values are `geojson`, `geojsonseq`, and `geoparquet`.
26
+ - `--output` or `-o`: output file path. When omitted, output is written to stdout.
27
+ - `--type` or `-t`: required Overture data type such as `building` or `place`.
28
+ - `--connect_timeout`: socket connection timeout in seconds.
29
+ - `--request_timeout`: socket read timeout in seconds on Windows and macOS.
30
+ - `--stac` or `--no-stac`: choose whether to resolve the latest release through the [STAC catalog](https://stac.overturemaps.org/).
31
+
32
+ To find a bounding box, [boundingbox.klokantech.com](https://boundingbox.klokantech.com/) can export coordinates in the format the CLI expects.
33
+
34
+ ## gers
35
+
36
+ `gers` looks up a feature in the GERS Registry and, when present in the latest release, writes it in the requested format.
37
+
38
+ ```bash
39
+ overturemaps gers 08f28d1c-bf17-4c5c-bc1b-0f1f7b0d4abc -f geojsonseq
40
+ ```
41
+
42
+ Options:
43
+
44
+ - `-f`: output format. Defaults to `geojsonseq`.
45
+ - `--output` or `-o`: output file path. When omitted, output is written to stdout.
46
+ - `--connect_timeout`: socket connection timeout in seconds.
47
+ - `--request_timeout`: socket read timeout in seconds on Windows and macOS.
48
+
49
+ ## releases
50
+
51
+ `releases` inspects published Overture releases.
52
+
53
+ ```bash
54
+ overturemaps releases list
55
+ overturemaps releases latest
56
+ overturemaps releases exists 2025-09-24.0
57
+ ```
58
+
59
+ Run `overturemaps releases --help` for the full subcommand set.
60
+
61
+ ## changelog
62
+
63
+ `changelog` queries GERS feature changes across releases.
64
+
65
+ ```bash
66
+ overturemaps changelog summary --theme=buildings
67
+ overturemaps changelog query --theme=places --bbox=-71.068,42.353,-71.058,42.363
68
+ ```
69
+
70
+ Run `overturemaps changelog --help` for the full subcommand set.
@@ -0,0 +1,16 @@
1
+ # Performance notes
2
+
3
+ Benchmarks use synthetic data on Apple M-series hardware.
4
+
5
+ | Output format | Geometry | Rows | Time |
6
+ | ------------- | -------- | ------ | ------------------ |
7
+ | GeoJSON | Points | 10 000 | 31 ms |
8
+ | GeoJSON | Polygons | 10 000 | 44 ms |
9
+ | GeoParquet | n/a | n/a | network/disk bound |
10
+
11
+ Run the benchmarks locally with:
12
+
13
+ ```bash
14
+ uv sync --group dev
15
+ pytest benchmarks/ -v
16
+ ```
@@ -0,0 +1,49 @@
1
+ # Python API guide
2
+
3
+ `overturemaps` is also a Python library. Import directly from `overturemaps` to query Overture data without using the CLI.
4
+
5
+ ## record_batch_reader
6
+
7
+ `record_batch_reader` returns a `pyarrow.RecordBatchReader`. This is the lowest-level entry point and works with Arrow-compatible tooling.
8
+
9
+ ```python
10
+ from overturemaps import record_batch_reader
11
+
12
+ bbox = (-71.068, 42.353, -71.058, 42.363)
13
+ reader = record_batch_reader("building", bbox=bbox)
14
+
15
+ if reader is not None:
16
+ table = reader.read_all()
17
+ print(table.schema)
18
+ ```
19
+
20
+ ## geodataframe
21
+
22
+ `geodataframe` loads data into a `geopandas.GeoDataFrame`.
23
+
24
+ Install optional dependencies with either `pip install overturemaps[geopandas]` or `pip install geopandas`.
25
+
26
+ ```python
27
+ from overturemaps import geodataframe
28
+
29
+ bbox = (-71.068, 42.353, -71.058, 42.363)
30
+ gdf = geodataframe("building", bbox=bbox)
31
+ print(gdf.head())
32
+ ```
33
+
34
+ ## Writing formats
35
+
36
+ Use `get_writer` and `copy` from `overturemaps.writers` to write data to GeoJSON, GeoJSONSeq, or GeoParquet without using the CLI.
37
+
38
+ ```python
39
+ from overturemaps import record_batch_reader
40
+ from overturemaps.writers import copy, get_writer
41
+
42
+ bbox = (-71.068, 42.353, -71.058, 42.363)
43
+ reader = record_batch_reader("building", bbox=bbox)
44
+
45
+ with get_writer("geojson", "boston.geojson", schema=reader.schema) as writer:
46
+ copy(reader, writer)
47
+ ```
48
+
49
+ Supported format strings: `geojson`, `geojsonseq`, `geoparquet`.
Binary file