Efficient token use

Tokens are rows: one per returned row, minimum one per request, and 10 per isochrone contour. So spending well is mostly about not asking for rows you will throw away. Here is the playbook.

Free things

• The whole catalog is free and keyless. GET /v1/meta/modes, /v1/meta/destination-types, /v1/meta/vintage, /v1/places, /v1/isochrone/meta, /v1/last-updated, and /v1/health cost nothing. Do all your lookups (type ids, city centres) before you spend a token.
• Revalidation is free. Cache a response with its ETag and send it back as If-None-Match; an unchanged response returns a free 304, even at a zero balance (the one exception is isochrones). Watch /v1/last-updated to know when the data has actually changed. See Conditional requests.
• Failed requests are never charged, and neither is population: passing include_population=true on an areal query adds a column, not tokens.

The big levers

The rows a query returns multiply out as modes x types x blocks. Each is a lever:

• Always pass mode. Omitting it returns all three modes, so three times the rows. Ask for the one you mean.
• Request leaf types, not parents. A parent type expands to its leaves: parks is four leaves (four times the rows), frequent_transit is two. Filter by the leaf you actually want.
• Shrink the area. Cost scales with the blocks you touch, and area grows with the square of the radius, so halving radius_m is roughly a quarter of the tokens.
• Filter server-side. max_minutes on the POI and catchment routes drops rows you would filter out anyway, so you pay for fewer.

Isochrones are the cheap reach primitive

An isochrone costs 10 tokens per contour regardless of how large the area is, and format=blocks returns every reachable block with its travel minutes. A whole 30-minute walkshed is 10 tokens, where the equivalent poi_catchment or blocks_query charges per block. Use catchments when you need per-POI stored times; use isochrones for “how far can I get” and for walkshed shapes. Four contours in one call cost the same as four separate calls but keep one consistent version.

Mechanics

• Page with limit=1000. It does not change the token cost (tokens are rows), but it cuts the number of requests tenfold, which matters against the 300 requests-per-minute limit. The SDKs follow cursors for you.
• Watch the balance while you learn. Every metered reply carries X-Tokens-Charged and X-Tokens-Remaining; both SDKs surface them, on df.attrs (Python) or the frame’s attributes (R) in the tabular modes, and on the reply in output="raw".
• Reuse block geometry. Block routes return GEOIDs; the SDKs join TIGER boundaries locally and cache them, so re-downloads cost time, not tokens. Pass a boundary frame you already have to skip the join, or use output="tabular" when you only want the numbers.

What it costs

Token packs are 10,000 tokens for $10, so a token is a tenth of a cent and 1,000 rows is a dollar. A few real queries, measured:

Query	Tokens	Cost
Any catalog or place lookup	0	free
One point or block summary	~5–20 rows	a fraction of a cent
A 30-minute walk isochrone	10	1¢
A three-contour isochrone (10/20/30 min)	30	3¢
Walk time to groceries for every block in Providence	3,165	~$3.17

New accounts start with 5,000 free tokens — enough for that whole Providence table with room to spare, or roughly 500 single-contour isochrones, at no cost.

What the tutorials cost

The SDK tutorials are designed to run comfortably within a new account’s signup grant. Each SDK tutorial page states its measured token cost at the top, so you can see what you are spending before you run it. The first-map tutorial is the cheapest place to start.