Rewrite the tutorials and README around interactive close_map() maps and the supermarket naming.

Author: Nathaniel Henry

README.md

@@ -23,16 +23,16 @@ You make requests through a client. Routes with geometry come back as
 GeoDataFrames, so you can map them right away.
 
 ```python
-from closecity import Client
+from closecity import Client, close_map
 
 # The key (ck_live_) comes from https://account.close.city (5,000 free tokens
 # on signup, no card). You can also set the CLOSECITY_KEY environment variable
 # and call Client() with no argument.
 close = Client("ck_live_your_key")   # use your own key here
 
-# 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()
+# Supermarkets within a 1.5 km walk of a point (type 30 is grocery stores):
+supermarkets = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1500, type = 30)
+close_map(supermarkets, color = "#e8590c")   # interactive map, bright hoverable points
 ```
 
 Catalog and lookup routes are free, need no key, and come back as data frames:
@@ -43,7 +43,7 @@ close.modes()                  # walk, bike, transit
 close.places("Providence")     # a city name to its GEOID and centre
 ```
 
-## Words you will see
+## Key terms
 
 A few terms come up throughout the API:
 
@@ -52,9 +52,9 @@ A few terms come up throughout the API:
 - **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.
+- **Isochrone** or **catchment.** Two views of the same reachability: the area you
+  can reach from a point within a time limit (an isochrone), or every block that
+  can reach a place (a catchment).
 
 ## Choosing an output
 

docs/getting_started.md

@@ -15,11 +15,11 @@ A short tour of the client. The tutorials go further.
 ```{code-cell} python
 :tags: [remove-cell]
 import os
-from closecity import Client
+from closecity import Client, close_map
 close = Client(os.environ.get("CLOSECITY_KEY"))
 ```
 
-## Words you will see
+## Key terms
 
 A few terms come up throughout:
 
@@ -28,15 +28,23 @@ A few terms come up throughout:
 - **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.
+- **Isochrone** or **catchment.** Two views of the same reachability: the area
+  reachable from a point within a time limit (an isochrone), or every block that
+  can reach a given place (a catchment).
+
+## Travel times
+
+Times to nearby places are **capped at 30 minutes** for each mode, and recorded in
+**whole minutes**. A missing time means the place is not reachable within the cap,
+not that it is zero. Isochrones are the exception: they are available for any
+budget up to an hour.
 
 ## Build a client
 
 You make every request through a client.
 
 ```python
-from closecity import Client
+from closecity import Client, close_map
 
 close = Client("ck_live_your_key")   # use your own key here
 ```
@@ -52,51 +60,47 @@ close.modes()
 
 Read the numeric id for a category from the catalog, and turn a city name into a
 GEOID and a centre point. Both are plain data frames, so you filter and index them
-the usual way.
+the usual way. The catalog's `name` column is the readable label ("Grocery
+stores"); the underscored `label` is the internal key you match on. A place lookup
+carries a `state`, so you can tell Providence, RI from the one in Utah.
 
 ```{code-cell} python
 types = close.destination_types()
-grocery = types.loc[types["label"] == "grocery_stores", "dest_type_id"].iloc[0]
+supermarket_dest_type = types.loc[types["label"] == "grocery_stores",
+                                  "dest_type_id"].iloc[0]
 
-matches = close.places("Providence")
-providence = matches.iloc[0]
-providence["geoid"]
+providence_ri = close.places("Providence").iloc[0]
+providence_ri[["name", "state", "geoid"]]
 ```
 
 ## Make a call and map it
 
-Routes with geometry return a GeoDataFrame, so you can map the result straight
-away.
+Routes with geometry return a GeoDataFrame. `close_map()` draws it on an
+interactive basemap in one line — bright, hoverable points here.
 
 ```{code-cell} python
-groceries = close.pois_search(lat = providence["lat"], lon = providence["lon"],
-                              radius_m = 1500, type = grocery)
-groceries.plot(color = "#202a5b")
+supermarkets = close.place_pois(providence_ri["geoid"], type = supermarket_dest_type)
+close_map(supermarkets, color = "#e8590c")
 ```
 
 ## Choose an output
 
-Every route returns tabular data by default. The `output` setting controls the
-shape:
-
-- `"spatial"` (the default) returns a GeoDataFrame where geometry applies, and a
-  plain DataFrame otherwise.
-- `"tabular"` returns a plain DataFrame for every route and never downloads block
-  boundaries. Reach for it when you only want the numbers.
-- `"raw"` returns the underlying reply, with the parsed body on `.data` and the
-  token counts alongside.
+Every route returns tabular data by default: a GeoDataFrame where geometry applies,
+a plain DataFrame otherwise. The `output` setting changes the shape — `"tabular"`
+never downloads boundaries, and `"raw"` returns the underlying reply with its
+metering and cursor fields. Set it on the client, or pass `output=` to one call.
 
-Set it on the client, or pass `output=` to a single call.
+The same block summary as a DataFrame (the default):
 
 ```{code-cell} python
-close.output = "raw"
-summary = close.block_summary("440070008001068", mode = "walk")
-summary.results
+close.block_summary("440070008001068", mode = "walk")
 ```
 
+...and as the raw reply, whose `results` you can index yourself:
+
 ```{code-cell} python
-:tags: [remove-cell]
-close.output = "spatial"
+raw = close.block_summary("440070008001068", mode = "walk", output = "raw")
+raw.results[:3]
 ```
 
 In the frame modes, the token counts and other reply metadata ride on `df.attrs`.

docs/index.rst

@@ -7,14 +7,14 @@ public transit. This is the data behind `close.city <https://close.city>`_.
 
 .. code-block:: python
 
-   from closecity import Client
+   from closecity import Client, close_map
 
    # The key (ck_live_) comes from https://account.close.city
    close = Client("ck_live_your_key")   # use your own key here
 
    # Routes with geometry return a GeoDataFrame, ready to map:
-   groceries = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1500)
-   groceries.plot()
+   supermarkets = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1500, type = 30)
+   close_map(supermarkets, color = "#e8590c")   # interactive map, bright hoverable points
 
 Results are tabular by default: a GeoDataFrame where geometry applies, a plain
 DataFrame otherwise. Install with ``pip install closecity``. The catalog and

docs/token_use.md

@@ -21,9 +21,9 @@ The API is metered in tokens: one per returned row, minimum one per request, and
 10 per isochrone contour. Tokens are rows, so spending well is mostly about not
 asking for rows you will throw away.
 
-## Free things
+## Free queries
 
-The whole catalog is free and keyless: `modes()`, `destination_types()`,
+Metadata queries are free and keyless: `modes()`, `destination_types()`,
 `vintage()`, `places()`, `isochrone_meta()`, `last_updated()`, and `health()`. Do
 your lookups before you spend a token.
 
@@ -44,8 +44,11 @@ again.not_modified   # True, and nothing was charged
 The rows a query returns multiply out as modes times types times blocks:
 
 - **Pass `mode`.** Omitting it returns all three modes, so three times the rows.
-- **Request leaf types, not parents.** A parent type expands to its leaves, so
-  `type = grocery` (one leaf) is a quarter of the rows of the `parks` parent.
+- **Filter by `type`.** The POI and areal routes take a destination `type`, so ask
+  the server for only the category you want rather than fetching everything and
+  filtering in pandas. Look the id up in `destination_types()`.
+- **Request leaf types, not parents.** A parent type expands to its leaves, so a
+  single leaf id is a fraction of the rows of a parent like `parks`.
 - **Shrink the area.** Cost grows with the square of `radius_m`, so halving the
   radius is roughly a quarter of the tokens.
 - **Use `max_minutes`.** It drops rows you would filter out anyway.
@@ -64,11 +67,18 @@ shed = close.isochrone(block = "440070008001068", minutes = 30, mode = "walk",
 ## Watch what you spend
 
 Every metered reply carries the token counts. In the frame output modes they ride
-on `df.attrs`; in `output="raw"` they are on the reply.
+on `df.attrs`; in `output="raw"` they are on the reply. Here the `type` filter asks
+only for supermarkets, so you pay for a handful of rows, not every POI in the
+radius:
 
 ```{code-cell} python
-groceries = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1200)
-groceries.attrs["tokens_charged"], groceries.attrs["tokens_remaining"]
+types = close.destination_types()
+supermarket_dest_type = types.loc[types["label"] == "grocery_stores",
+                                  "dest_type_id"].iloc[0]
+
+supermarkets = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1200,
+                                 type = supermarket_dest_type)
+supermarkets.attrs["tokens_charged"], supermarkets.attrs["tokens_remaining"]
 ```
 
 When you only want the numbers, `output="tabular"` skips the block-boundary

docs/tutorials/amenity_basket.md

@@ -11,7 +11,7 @@ kernelspec:
 # The amenity basket
 
 A city planner wants every resident to be able to walk to a basket of six everyday
-amenities: a grocery store, a library, a park, a frequent-transit stop, a restaurant,
+amenities: a supermarket, a library, a park, a frequent-transit stop, a restaurant,
 and a cafe. This tutorial measures how many residents already have that, and shows
 where the gaps are. The idea follows
 [this analysis](https://nathenry.com/writing/2023-02-07-seattle-walkability.html),
@@ -22,7 +22,7 @@ here applied to Richmond, Virginia.
 ```{code-cell} python
 :tags: [remove-cell]
 import os
-from closecity import Client
+from closecity import Client, close_map
 close = Client(os.environ.get("CLOSECITY_KEY"))
 ```
 
@@ -32,7 +32,7 @@ Read the six category ids from the free catalog, and turn the city name into a c
 point.
 
 ```python
-from closecity import Client
+from closecity import Client, close_map
 
 close = Client("ck_live_your_key")   # use your own key here
 ```
@@ -41,7 +41,7 @@ close = Client("ck_live_your_key")   # use your own key here
 types = close.destination_types()
 ids = dict(zip(types["label"], types["dest_type_id"]))
 basket = {
-    "grocery": ids["grocery_stores"],
+    "supermarket": ids["grocery_stores"],
     "library": ids["libraries"],
     "park": ids["parks"],
     "transit": ids["frequent_transit"],
@@ -54,15 +54,17 @@ city = close.places("Richmond").iloc[0]
 
 ## Pull the blocks, with population
 
-One call gets the walk time from every block near downtown to each of the six
-categories, along with each block's population.
+One call gets the walk time from every block to each of the six categories, plus
+each block's population. To keep this tutorial cheap we take the central blocks
+within a radius; `place_blocks(city["geoid"])` pulls **every** block in the city
+the same way (at a higher token cost).
 
 ```{code-cell} python
 blocks = close.blocks_query(
     center = {"lon": city["lon"], "lat": city["lat"]}, radius_m = 2500,
     mode = "walk", type = list(basket.values()), include_population = True)
 
-one_per_block = blocks.drop_duplicates("geoid")
+one_per_block = blocks.drop_duplicates("geoid").copy()
 total_pop = one_per_block["population"].sum()
 ```
 
@@ -78,14 +80,13 @@ for name, type_id in basket.items():
     print(f"{name:11} {100 * pop / total_pop:3.0f}%")
 ```
 
-Map one amenity to see the pattern.
+Map one amenity — every block shown, the covered ones highlighted.
 
 ```{code-cell} python
 near_transit = set(blocks.loc[(blocks.dest_type_id == basket["transit"]) &
                               (blocks.travel_time <= 15), "geoid"])
-one_per_block = one_per_block.assign(
-    has_transit = one_per_block.geoid.isin(near_transit))
-one_per_block.plot(column = "has_transit", cmap = "Greens")
+one_per_block["has_transit"] = one_per_block.geoid.isin(near_transit)
+close_map(one_per_block, highlight = "has_transit", color = "#058040")
 ```
 
 ## The 15-minute-city score
@@ -97,9 +98,8 @@ already pulled, so it costs nothing more.
 ```{code-cell} python
 covered = blocks[blocks.travel_time <= 15]
 score = covered.groupby("geoid")["dest_type_id"].nunique()
-one_per_block = one_per_block.assign(
-    score = one_per_block.geoid.map(score).fillna(0).astype(int))
-one_per_block.plot(column = "score", cmap = "viridis", legend = True)
+one_per_block["score"] = one_per_block.geoid.map(score).fillna(0).astype(int)
+close_map(one_per_block, fill = "score")
 ```
 
 ## Who can reach all six
@@ -117,9 +117,8 @@ basket_pop = one_per_block.loc[one_per_block.geoid.isin(covered_all),
                                "population"].sum()
 print(f"All six amenities: {100 * basket_pop / total_pop:.0f}% of residents")
 
-one_per_block = one_per_block.assign(
-    full_basket = one_per_block.geoid.isin(covered_all))
-one_per_block.plot(column = "full_basket", cmap = "Oranges")
+one_per_block["full_basket"] = one_per_block.geoid.isin(covered_all)
+close_map(one_per_block, highlight = "full_basket", color = "#f36e21")
 ```
 
 ## Which amenity to add first
@@ -137,10 +136,28 @@ for name, type_id in basket.items():
     print(f"{name:11} {pop:6.0f} residents would gain access")
 ```
 
-Map the uncovered blocks to see where new amenities would do the most good.
+## Site a new supermarket
+
+The counts above say *which* amenity to add; the next question is *where*. Take a
+candidate site near the city centre and ask how many residents would newly gain a
+supermarket within a 15-minute walk if one opened there. A `direction="to"`
+isochrone gives exactly the blocks that could reach the site on foot in 15 minutes.
+
+```{code-cell} python
+reachable = close.isochrone(lon = city["lon"], lat = city["lat"], mode = "walk",
+                            direction = "to", minutes = 15, format = "blocks")
+
+near_supermarket = set(blocks.loc[(blocks.dest_type_id == basket["supermarket"]) &
+                                  (blocks.travel_time <= 15), "geoid"])
+newly_served = set(reachable.geoid) - near_supermarket
+gain_pop = one_per_block.loc[one_per_block.geoid.isin(newly_served),
+                             "population"].sum()
+print(f"A supermarket here would newly serve {gain_pop:.0f} residents")
+```
+
+Map the whole city and highlight the blocks that would newly gain access.
 
 ```{code-cell} python
-one_per_block = one_per_block.assign(
-    uncovered = one_per_block.geoid.isin(uncovered))
-one_per_block.plot(column = "uncovered", cmap = "Blues")
+one_per_block["newly_served"] = one_per_block.geoid.isin(newly_served)
+close_map(one_per_block, highlight = "newly_served", color = "#e8590c")
 ```