Add the closecity Python client with Sphinx docs and tutorials

Author: Nathaniel Henry

.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev,geo]"
+      - run: ruff check src tests
+      - run: pytest -q

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[docs]"
+      - run: sphinx-build -b html docs docs/_build/html -W --keep-going
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: publish
+
+# Publishes to PyPI via OIDC trusted publishing when a GitHub Release is
+# published. Configure the trusted publisher on PyPI first (project "closecity",
+# workflow "publish.yml", environment "pypi").
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/closecity
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+# Sphinx build output
+docs/_build/

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 1.0.0
+
+First public release of the `closecity` Python client for the Close API
+(api.close.city).
+
+- A thin, typed `Client` over the metered, read-only public endpoints: catalog,
+  block/point summaries and POIs, POI search/detail/catchment, areal block
+  queries, and isochrones.
+- First-class metering (`tokens_charged` / `tokens_remaining`), ETag/304
+  conditional requests, keyset pagination (`Paginator`), and typed RFC 9457
+  errors.
+- `places()` place-name lookup (city/town → GEOID + centroid).
+- Opt-in spatial output: `Reply.to_geopandas()` / `Paginator.to_geopandas()`
+  (POI points, isochrone polygons, and census-block joins) under the `geo` extra.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Close
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,122 @@
+# closecity — Python client for the Close API
+
+Travel times from every US census block to nearby points of interest, by walking,
+biking, and public transit — the data behind [close.city](https://close.city),
+over the [Close API](https://api.close.city).
+
+**Documentation:** https://henryspatialanalysis.github.io/closecity-python/
+
+```bash
+pip install closecity
+pip install "closecity[geo]"   # + GeoPandas output (to_geopandas)
+```
+
+## Quickstart
+
+```python
+from closecity import Client
+
+# The API key (ck_live_… / ck_test_…) is created at https://account.close.city.
+with Client("ck_live_your_key_here") as close:
+    # Fastest travel time to each category from a census block.
+    summary = close.block_summary("410390020001010", mode = ["walk", "transit"])
+    for row in summary.results:
+        print(row["dest_type_id"], row["mode"], row["travel_time"])
+
+    # Metering is surfaced on every metered reply.
+    print(summary.tokens_charged, "charged;", summary.tokens_remaining, "left")
+```
+
+Free routes (catalog, place lookup, health) need no key:
+
+```python
+from closecity import Client
+close = Client()
+print(close.modes().data["modes"])
+print(close.last_updated().data["last_updated"])
+
+# Resolve a city name to its census place GEOID + centroid:
+print(close.places("Providence").data["places"][0])
+```
+
+## Pagination
+
+List endpoints return a `Paginator` that follows the opaque keyset cursor for you.
+Iterate it for every record, or use `.pages()` for per-page metadata:
+
+```python
+# Every POI near a point, across all pages:
+for poi in close.pois_search(lat = 44.05, lon = -123.09, radius_m = 2000):
+    print(poi["name"], poi["address"]["city"])
+
+# Or page-by-page, watching the token balance drop:
+for page in close.block_pois("410390020001010", limit = 500).pages():
+    print(len(page.results), "rows;", page.tokens_remaining, "tokens left")
+```
+
+Cursors are opaque and signed — never construct or modify them.
+
+## Conditional requests (free revalidation)
+
+Metered `GET`s return an `ETag`. Send it back to revalidate for free — a `304`
+costs no tokens, even at a zero balance:
+
+```python
+first = close.block_summary("410390020001010")
+again = close.block_summary("410390020001010", if_none_match = first.etag)
+if again.not_modified:
+    ...  # your cached copy is still current; nothing was charged
+```
+
+## Isochrones
+
+```python
+iso = close.isochrone(block = "410390020001010", contours = [15, 30, 45],
+                      mode = "walk", direction = "to")
+for feature in iso.data["features"]:
+    print(feature["properties"]["contour"], feature["properties"]["reachable_blocks"])
+```
+
+## Errors
+
+Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `problem+json`,
+mapped to exceptions. Catch a precise class or the `CloseAPIError` base; the stable
+machine key is `err.slug`:
+
+```python
+from closecity import CloseAPIError, TokensExhaustedError, RateLimitedError
+
+try:
+    close.block_summary("000000000000000")
+except TokensExhaustedError:
+    ...  # buy more tokens at account.close.city
+except RateLimitedError as err:
+    time.sleep(err.retry_after or 1)
+except CloseAPIError as err:
+    print(err.slug, err.status, err.title, err.request_id)
+```
+
+## Spatial output
+
+With `pip install "closecity[geo]"`, turn any reply into a GeoDataFrame — POIs
+become points, isochrones become polygons, and block replies join census-block
+boundaries:
+
+```python
+pts = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1500).to_geopandas()
+iso = close.isochrone(block = "440070036001010", minutes = 15).to_geopandas()
+```
+
+## Reference
+
+- Documentation: https://henryspatialanalysis.github.io/closecity-python/
+- Interactive API: https://api.close.city/docs
+- Machine-readable contract: https://api.close.city/openapi.json
+
+## Development
+
+```bash
+pip install -e '.[dev,geo]'
+pytest        # unit tests (no network — httpx MockTransport)
+ruff check src tests
+```

docs/_static/close-logo.png

@@ -0,0 +1,14 @@
+/* Close type system, mirroring docs.close.city: Figtree for body, Inconsolata
+   for code. Loaded from Google Fonts (the same source the app and Starlight
+   docs use). Falls back to system fonts if offline. */
+@import url("https://fonts.googleapis.com/css2?family=Figtree:ital,wght@0,400;0,500;0,600;0,700;1,400&family=Inconsolata:wght@400;600&display=swap");
+
+:root {
+  --font-stack: "Figtree", system-ui, -apple-system, "Helvetica", sans-serif;
+  --font-stack--monospace: "Inconsolata", ui-monospace, "SFMono-Regular", monospace;
+}
+
+/* The Close wordmark accent: the terminal yellow dot on the logo. */
+.sidebar-brand-text {
+  font-weight: 700;
+}