Quickstart

This walks from an empty terminal to a real walkability reading. The first step runs with no account at all. The rest need one free key, which takes about a minute to get.

1. Look up a place (no key needed)

The catalog and place-lookup routes are free and need no key. Turn a city name into a GEOID and a centre point:

curl "https://api.close.city/v1/places?q=Providence&limit=1"

{ "places": [
  { "name": "Providence", "geoid": "4459000",
    "lon": -71.41872, "lat": 41.82301 }
] }

That centre point is the input to the metered routes below.

2. Get a free key

Metered routes need an API key. Create one at account.close.city: enter your email, click the link (or type the six-digit code back into the page), and open the dashboard. New accounts receive 5,000 free tokens, and no card is required. On the dashboard, choose Create key and copy the ck_live_ key it shows once.

Set it as an environment variable so the examples below can read it:

export CLOSECITY_KEY="ck_live_your_key_here"

(Building an agent that signs up on a user’s behalf? See For AI agents for the same flow over JSON.)

3. Read the walkability of a point

Ask how long it takes to walk to each kind of amenity from that centre point:

curl -H "Authorization: Bearer $CLOSECITY_KEY" \
  "https://api.close.city/v1/point/summary?lat=41.82301&lon=-71.41872&mode=walk"

{ "resolved_block": "440070008003031",
  "results": [
    { "dest_type_id": 1, "mode": "walk", "travel_time": 15.0 },
    { "dest_type_id": 7, "mode": "walk", "travel_time": 15.0 }
  ] }

Each row is the walk time in minutes to the nearest amenity of one type. Join GET /v1/meta/destination-types (free) to turn dest_type_id into a name. A missing type means it is not reachable on foot within 30 minutes — see The data. That call charged one token per returned row; watch the X-Tokens-Charged and X-Tokens-Remaining response headers to track spend.

4. Do it in Python or R

The SDKs return the same data as a pandas/geopandas frame (Python) or a data frame / sf object (R), ready to map. Both read CLOSECITY_KEY from the environment.

pip install closecity

from closecity import Client

close = Client()   # reads CLOSECITY_KEY
here = close.places("Providence").iloc[0]
summary = close.point_summary(lat = here.lat, lon = here.lon, mode = "walk")
print(summary)

install.packages("closecity")   # or from source until it lands on CRAN
library(closecity)

close <- close_client()   # reads CLOSECITY_KEY
here <- close$places("Providence")[1, ]
summary <- close$point_summary(lat = here$lat, lon = here$lon, mode = "walk")
print(summary)

Where to go next

• The data — what a travel time means, and why absent is not zero.
• Efficient token use — what queries cost, in tokens and dollars.
• The Python and R SDKs each carry three worked tutorials that map a neighbourhood end to end.