Return GeoDataFrames by default and rewrite the docs for beginners

Author: Nathaniel Henry

CHANGELOG.md

@@ -5,12 +5,12 @@
 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.
+- A typed `Client` over the metered, read-only public endpoints: catalog, place
+  lookup, block and point summaries and POIs, POI search, detail, and catchment,
+  areal block queries, and isochrones.
+- Feature methods return `geopandas.GeoDataFrame` objects by default. Pass
+  `spatial=False` for the raw `Reply` / `Paginator`. Block boundaries are joined
+  with `pygris` (the `tiger` extra).
+- First-class metering (`tokens_charged`, `tokens_remaining`), ETag/304 conditional
+  requests, keyset pagination (`Paginator`), and typed RFC 9457 errors.
+- `places()` looks up a city or town by name and returns its GEOID and centre.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Close
+Copyright (c) 2026 Henry Spatial Analysis
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,110 +1,84 @@
-# closecity — Python client for the Close API
+# closecity
 
-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).
+Python client for the Close API. Get travel times from every US census block to
+nearby places, on foot, by bike, and by public transit. This is the data behind
+[close.city](https://close.city), read over the [Close API](https://api.close.city).
 
 **Documentation:** https://henryspatialanalysis.github.io/closecity-python/
 
+## Install
+
 ```bash
 pip install closecity
-pip install "closecity[geo]"   # + GeoPandas output (to_geopandas)
+pip install "closecity[tiger]"   # to auto-download census-block boundaries
 ```
 
-## Quickstart
+This pulls in `httpx` and `geopandas`, so feature methods return GeoDataFrames out
+of the box.
 
-```python
-from closecity import Client
+## A first call
 
-# 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:
+You make requests through a client. Feature results come back as GeoDataFrames, so
+you can map them right away.
 
 ```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])
-```
+# The key (ck_live_ or ck_test_) comes from https://account.close.city
+close = Client("ck_live_your_key")   # use your own key here
 
-## Pagination
+# Grocery stores within a 1.5 km walk of a point, as points:
+groceries = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1500, type = 30)
+groceries.plot()
+```
 
-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:
+Catalog and lookup routes are free and need no key:
 
 ```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")
+close = Client()
+close.modes().data["modes"]                    # walk, bike, transit
+close.places("Providence").data["places"][0]   # a city name to its GEOID and centre
 ```
 
-Cursors are opaque and signed — never construct or modify them.
+## Words you will see
 
-## Conditional requests (free revalidation)
+A few terms come up throughout the API:
 
-Metered `GET`s return an `ETag`. Send it back to revalidate for free — a `304`
-costs no tokens, even at a zero balance:
+- **Census block.** The smallest area the Census Bureau publishes. Each one has a
+  15-digit id called a **GEOID**.
+- **Destination type.** A category of place, such as grocery stores or libraries.
+  Each type has a numeric id. Look them up with `close.destination_types()`.
+- **Mode.** How someone travels: walk, bike, or transit.
+- **Isochrone.** The area you can reach from a point within a time limit, as a
+  polygon.
+- **Catchment.** The reverse of an isochrone: every block that can reach a place.
 
-```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
-```
+## Spatial output, on or off
 
-## Isochrones
+Feature methods return GeoDataFrames by default. Block routes join census-block
+boundaries for you, using `pygris` (the `tiger` extra) to download them once. To work
+with the raw data instead, build the client with `spatial=False`:
 
 ```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"])
+close = Client("ck_live_your_key", spatial = False)   # use your own key here
+for poi in close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1500):
+    print(poi["name"])
 ```
 
-## Errors
+## Handling 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`:
+Problem responses become typed exceptions. Catch a specific one, or the
+`CloseAPIError` base.
 
 ```python
-from closecity import CloseAPIError, TokensExhaustedError, RateLimitedError
+from closecity import TokensExhaustedError, CloseAPIError
 
 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()
+    print(err.status, err.slug)
 ```
 
 ## Reference
@@ -116,7 +90,7 @@ iso = close.isochrone(block = "440070036001010", minutes = 15).to_geopandas()
 ## Development
 
 ```bash
-pip install -e '.[dev,geo]'
-pytest        # unit tests (no network — httpx MockTransport)
+pip install -e '.[dev]'
+pytest        # unit tests, no network (httpx MockTransport)
 ruff check src tests
 ```

docs/getting_started.rst

@@ -1,103 +1,108 @@
 Getting started
 ===============
 
-This is a five-minute tour of the client. For end-to-end analyses see the
-:doc:`tutorials <tutorials/index>`.
+A short tour of the client. The tutorials go further.
 
-A client
---------
+Words you will see
+------------------
+
+A few terms come up throughout:
+
+- **Census block.** The smallest area the Census Bureau publishes. Each one has a
+  15-digit id, its **GEOID**.
+- **Destination type.** A category of place, such as grocery stores or libraries.
+  Every type has a numeric id.
+- **Mode.** How someone travels: walk, bike, or transit.
+- **Isochrone.** The area reachable from a point within a time limit, as a polygon.
+- **Catchment.** The reverse: every block that can reach a given place.
+
+Build a client
+--------------
+
+You make every request through a client.
 
 .. code-block:: python
 
    from closecity import Client
 
-   close = Client("ck_live_your_key_here")   # or Client() for the free routes
+   # The key (ck_live_ or ck_test_) comes from https://account.close.city
+   close = Client("ck_live_your_key")   # use your own key here
 
-``Client`` is usable as a context manager (``with Client(...) as close:``) so the
-underlying HTTP connection is closed for you.
-
-Free catalog (no key)
----------------------
+The catalog and lookup routes are free, so you can also start without a key:
 
 .. code-block:: python
 
    close = Client()
-   print(close.modes().data["modes"])                 # walk / bike / transit
-   print(close.destination_types().data["destination_types"][:3])
-   print(close.last_updated().data["last_updated"])
+   close.modes().data["modes"]                    # walk, bike, transit
+   close.last_updated().data["last_updated"]
 
-Use :meth:`~closecity.Client.destination_types` to find the numeric ``type`` ids the
-data routes filter on (e.g. grocery ``30``, restaurants ``27``, cafes ``31``,
-libraries ``43``, parks ``63``, frequent-transit stops ``61``).
+Look things up instead of guessing
+----------------------------------
 
-One metered call
-----------------
+Two free calls save you from memorising codes. Read the numeric id for a category
+from the catalog, and turn a city name into a GEOID and a centre point.
 
 .. code-block:: python
 
-   summary = close.block_summary("250173523004004", mode="walk")
-   for row in summary.results:
-       print(row["dest_type_id"], row["mode"], row["travel_time"])
+   types = close.destination_types().data["destination_types"]
+   ids = {t["label"]: t["dest_type_id"] for t in types}
+   grocery = ids["grocery_stores"]
 
-Every metered reply carries its accounting:
+   providence = close.places("Providence").data["places"][0]
+   providence["geoid"]
 
-.. code-block:: python
+Make a call and map it
+----------------------
 
-   print(summary.tokens_charged, "charged;", summary.tokens_remaining, "left")
+Feature methods return a :class:`geopandas.GeoDataFrame`, so you can map the result
+straight away.
+
+.. code-block:: python
 
-Metering is **1 token per returned row** (minimum 1 per request); isochrones are the
-exception at **10 tokens per contour**. A ``304`` revalidation is free.
+   groceries = close.pois_search(lat = providence["lat"], lon = providence["lon"],
+                                 radius_m = 1500, type = grocery)
+   groceries.plot(color = "#202a5b")     # needs matplotlib
 
-Pagination
-----------
+Turn spatial output off
+-----------------------
 
-List endpoints return a :class:`~closecity.Paginator` that transparently follows the
-opaque cursor:
+Set ``spatial=False`` to work with the raw data. Then list routes return a
+:class:`~closecity.Paginator` you can iterate.
 
 .. code-block:: python
 
-   pois = close.pois_search(lat=41.823, lon=-71.412, radius_m=1500, type=31)
-   for poi in pois:                 # every record across all pages
-       print(poi["name"], poi["lat"], poi["lon"])
+   close = Client("ck_live_your_key", spatial = False)   # use your own key here
+   for poi in close.pois_search(lat = providence["lat"], lon = providence["lon"],
+                                radius_m = 1500):
+       print(poi["name"])
 
-   # or page-by-page, to read per-page token metadata:
-   for page in close.pois_search(lat=41.823, lon=-71.412, radius_m=1500).pages():
-       print(len(page.results), page.tokens_remaining)
+Block methods join census-block boundaries for you, using the ``pygris`` package
+(``pip install "closecity[tiger]"``) to download them once.
 
-Conditional requests (free revalidation)
------------------------------------------
+Conditional requests
+--------------------
+
+Metered routes return an ``ETag``. Send it back to revalidate for free.
 
 .. code-block:: python
 
-   first = close.block_summary("250173523004004")
-   again = close.block_summary("250173523004004", if_none_match=first.etag)
-   assert again.not_modified          # 304 — no tokens charged
+   close = Client("ck_live_your_key", spatial = False)   # use your own key here
+   first = close.block_summary("440070036001010")
+   again = close.block_summary("440070036001010", if_none_match = first.etag)
+   assert again.not_modified
 
 Errors
 ------
 
-Problem+JSON responses become typed exceptions:
+Problem responses become typed exceptions.
 
 .. code-block:: python
 
    from closecity import TokensExhaustedError, CloseAPIError
 
    try:
-       close.block_summary("250173523004004")
+       close.block_summary("000000000000000")
    except TokensExhaustedError:
-       ...                            # out of tokens (HTTP 429)
+       ...
    except CloseAPIError as err:
        print(err.status, err.slug)
-
-Spatial output
---------------
-
-Turn a reply into a GeoDataFrame (needs ``pip install "closecity[geo]"``):
-
-.. code-block:: python
-
-   pts = close.pois_search(lat=41.823, lon=-71.412, radius_m=1500).to_geopandas()
-   iso = close.isochrone(block="250173523004004", minutes=15).to_geopandas()
-
-POIs become point geometry and isochrones become polygons offline; block replies
-join to census-block boundaries (pass ``block_geometry=`` or ``fetch=True``).