Close API

Look up a US city or town by name (free, no key). Returns matches with their census place GEOID and centre point (lon/lat). The entry point: feed a GEOID to blocks_in_area, or a centre to walkability_summary.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "City or town name, e.g. 'Providence'."
    },
    "limit": {
      "type": "integer",
      "description": "Max matches (1-20).",
      "default": 5
    }
  },
  "required": [
    "query"
  ]
}

List the travel modes and the destination-type taxonomy (free, no key). Use it to resolve type names to the numeric ids the other tools take. Modes are walk, bike, transit — there is no drive mode.

{
  "type": "object",
  "properties": {}
}

Fastest travel time from a location to each destination category, by mode (metered: 1 token per returned row). One origin: block_geoid or lat+lon. Many origins (up to 250): block_geoids or points — one batch call and one rate-limit request, with rows tagged by origin. Batching saves requests and context, not tokens: it still charges per row. A non-empty truncated (+ truncated_reason) means the balance or row budget cut the batch short. A missing category means it is not reachable within 30 minutes.

{
  "type": "object",
  "properties": {
    "block_geoid": {
      "type": "string",
      "description": "15-digit census block GEOID."
    },
    "lat": {
      "type": "number"
    },
    "lon": {
      "type": "number"
    },
    "block_geoids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Many block GEOIDs — one batch call."
    },
    "points": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lat": {
            "type": "number"
          },
          "lon": {
            "type": "number"
          }
        },
        "required": [
          "lat",
          "lon"
        ]
      },
      "description": "Many lat/lon points — one batch call."
    },
    "mode": {
      "type": "string",
      "description": "walk, bike, or transit. Omit for all three."
    }
  }
}

Nearby points of interest and the travel time to each, from a location (metered: 1 token per returned row). One origin: block_geoid or lat+lon; keep limit small to control spend and context size. Many origins (up to 250): block_geoids or points — one batch call and one rate-limit request, rows tagged by origin, no limit/pagination, so filter with type/mode/max_minutes. Batching saves requests and context, not tokens: it still charges per row. A non-empty truncated (+ truncated_reason) means the balance or row budget cut the batch short.

{
  "type": "object",
  "properties": {
    "block_geoid": {
      "type": "string"
    },
    "lat": {
      "type": "number"
    },
    "lon": {
      "type": "number"
    },
    "block_geoids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Many block GEOIDs — one batch call."
    },
    "points": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lat": {
            "type": "number"
          },
          "lon": {
            "type": "number"
          }
        },
        "required": [
          "lat",
          "lon"
        ]
      },
      "description": "Many lat/lon points — one batch call."
    },
    "type": {
      "type": "integer",
      "description": "Destination type id (see get_catalog)."
    },
    "mode": {
      "type": "string",
      "description": "walk, bike, or transit."
    },
    "max_minutes": {
      "type": "integer",
      "description": "Upper bound on travel time (<=30)."
    },
    "limit": {
      "type": "integer",
      "description": "Max rows (first page).",
      "default": 25
    }
  }
}

The area reachable from a location within a time budget, as GeoJSON contours (metered: 10 tokens per contour). Give block_geoid or lat+lon. Defaults to a single 30-minute contour; ask for more only when needed (bodies can be large).

{
  "type": "object",
  "properties": {
    "block_geoid": {
      "type": "string"
    },
    "lat": {
      "type": "number"
    },
    "lon": {
      "type": "number"
    },
    "mode": {
      "type": "string",
      "description": "walk, bike, or transit.",
      "default": "walk"
    },
    "minutes": {
      "type": "integer",
      "description": "A single threshold (1-60).",
      "default": 30
    },
    "contours": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Up to four ascending thresholds, instead of minutes."
    },
    "direction": {
      "type": "string",
      "description": "'from' the origin (default) or 'to' it."
    }
  }
}

Per-block travel times for every census block in an area (metered: 1 token per returned row). Give place_geoid (from find_place) for a whole city, or center {lat, lon} + radius_m. Rows carry a numeric mode_id.

{
  "type": "object",
  "properties": {
    "place_geoid": {
      "type": "string",
      "description": "Census place GEOID (a whole city/town)."
    },
    "lat": {
      "type": "number",
      "description": "Circle centre latitude (with lon + radius_m)."
    },
    "lon": {
      "type": "number",
      "description": "Circle centre longitude."
    },
    "radius_m": {
      "type": "number",
      "description": "Circle radius in metres (<=28000)."
    },
    "type": {
      "type": "integer",
      "description": "Destination type id (see get_catalog)."
    },
    "mode": {
      "type": "string",
      "description": "walk, bike, or transit."
    },
    "limit": {
      "type": "integer",
      "description": "Max rows (first page).",
      "default": 100
    }
  }
}

Check the token balance of the API key in use, without spending any tokens. Works even at a zero balance. Requires the Authorization bearer key.

{
  "type": "object",
  "properties": {}
}

Start free sign-up for the user: email them a six-digit code. The user must read the code from their own inbox and give it to you, then call redeem_code. This is how an agent gets the user an API key (5,000 free tokens, no card).

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "The user's email address."
    }
  },
  "required": [
    "email"
  ]
}

Complete sign-up with the six-digit code the user received, and return a new API key (shown once). Call request_sign_in first. The key grants 5,000 free tokens; store it and pass it as the Authorization bearer on future calls.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "description": "The six-digit code from the email."
    },
    "label": {
      "type": "string",
      "description": "Optional label for the key.",
      "default": "mcp-agent"
    }
  },
  "required": [
    "email",
    "code"
  ]
}

Get a Stripe Checkout URL for the Close+ membership ($10/month: 5,000 API tokens granted monthly plus member features on the close.city map). The user pays in their own browser: give them the returned URL and stop. Needs a fresh six-digit code from request_sign_in, read by the user from their own inbox.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "description": "The six-digit code from the email."
    }
  },
  "required": [
    "email",
    "code"
  ]
}