{ "components": { "schemas": { "Address": { "description": "A POI street address; every field is nullable. (shape.shape_pois,\nqueries.pois.detail)", "properties": { "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "street": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Street" }, "zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Zip" } }, "title": "Address", "type": "object" }, "ArealBlockResult": { "description": "One (block, category, mode) row. NOTE the int `mode_id` here, unlike the\nstring `mode` on the block/point routes. (queries.spatial._pivot)", "properties": { "dest_type_id": { "title": "Dest Type Id", "type": "integer" }, "geoid": { "title": "Geoid", "type": "string" }, "mode_id": { "description": "Numeric mode id (see /v1/meta/modes)", "title": "Mode Id", "type": "integer" }, "population": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Present only when include_population=true", "title": "Population" }, "travel_time": { "description": "Minutes, 1 decimal", "title": "Travel Time", "type": "number" } }, "required": [ "geoid", "dest_type_id", "mode_id", "travel_time" ], "title": "ArealBlockResult", "type": "object" }, "ArealBlocksResponse": { "description": "POST /v1/blocks/query and GET /v1/places/{geoid}/blocks\n(routers.spatial._paged)", "properties": { "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "results": { "items": { "$ref": "#/components/schemas/ArealBlockResult" }, "title": "Results", "type": "array" } }, "required": [ "results" ], "title": "ArealBlocksResponse", "type": "object" }, "BlockMeta": { "description": "Census-block metadata. (queries.blocks.summary_rows -> block_meta)", "properties": { "geoid": { "description": "15-digit census block GEOID", "title": "Geoid", "type": "string" }, "land_area_m2": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Block land area in square metres", "title": "Land Area M2" }, "population": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Population" } }, "required": [ "geoid" ], "title": "BlockMeta", "type": "object" }, "BlockPoisResponse": { "description": "GET /v1/blocks/{geoid}/pois (routers.blocks.blocks_pois)", "properties": { "block_geoid": { "title": "Block Geoid", "type": "string" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "results": { "items": { "$ref": "#/components/schemas/PoiTime" }, "title": "Results", "type": "array" } }, "required": [ "block_geoid", "results" ], "title": "BlockPoisResponse", "type": "object" }, "BlockSummaryResponse": { "description": "GET /v1/blocks/{geoid}/summary (routers.blocks.blocks_summary)", "properties": { "block": { "$ref": "#/components/schemas/BlockMeta" }, "results": { "items": { "$ref": "#/components/schemas/CategoryTime" }, "title": "Results", "type": "array" } }, "required": [ "block", "results" ], "title": "BlockSummaryResponse", "type": "object" }, "BlocksQuery": { "properties": { "center": { "anyOf": [ { "$ref": "#/components/schemas/Center" }, { "type": "null" } ] }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "include_population": { "default": false, "title": "Include Population", "type": "boolean" }, "limit": { "anyOf": [ { "maximum": 1000.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "mode": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Mode" }, "polygon": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "GeoJSON Polygon or MultiPolygon geometry", "title": "Polygon" }, "radius_m": { "anyOf": [ { "exclusiveMinimum": 0.0, "maximum": 28000.0, "type": "number" }, { "type": "null" } ], "title": "Radius M" }, "type": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Type" } }, "title": "BlocksQuery", "type": "object" }, "CatchmentResponse": { "properties": { "dest_id": { "title": "Dest Id", "type": "integer" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "results": { "items": { "$ref": "#/components/schemas/CatchmentResult" }, "title": "Results", "type": "array" } }, "required": [ "dest_id", "results" ], "title": "CatchmentResponse", "type": "object" }, "CatchmentResult": { "description": "One block that can reach the POI, by mode. (shape.shape_catchment)", "properties": { "geoid": { "title": "Geoid", "type": "string" }, "mode": { "title": "Mode", "type": "string" }, "travel_time": { "description": "Minutes, 1 decimal", "title": "Travel Time", "type": "number" } }, "required": [ "geoid", "mode", "travel_time" ], "title": "CatchmentResult", "type": "object" }, "CategoryTime": { "description": "Fastest travel time to one destination category by one mode.\n(shape.shape_summary)", "properties": { "dest_type_id": { "title": "Dest Type Id", "type": "integer" }, "mode": { "description": "Travel mode label, e.g. 'walk'", "title": "Mode", "type": "string" }, "travel_time": { "description": "Minutes, capped at 30, 1 decimal", "title": "Travel Time", "type": "number" } }, "required": [ "dest_type_id", "mode", "travel_time" ], "title": "CategoryTime", "type": "object" }, "Center": { "properties": { "lat": { "maximum": 90.0, "minimum": -90.0, "title": "Lat", "type": "number" }, "lon": { "maximum": 180.0, "minimum": -180.0, "title": "Lon", "type": "number" } }, "required": [ "lon", "lat" ], "title": "Center", "type": "object" }, "DestinationType": { "description": "One node in the destination-type taxonomy.\n(routers.meta.meta_destination_types)", "properties": { "dest_type_id": { "title": "Dest Type Id", "type": "integer" }, "is_leaf": { "title": "Is Leaf", "type": "boolean" }, "label": { "title": "Label", "type": "string" }, "leaf_ids": { "description": "Leaf type ids this node expands to in travel-time filters", "items": { "type": "integer" }, "title": "Leaf Ids", "type": "array" }, "name": { "title": "Name", "type": "string" } }, "required": [ "dest_type_id", "name", "label", "is_leaf", "leaf_ids" ], "title": "DestinationType", "type": "object" }, "DestinationTypesResponse": { "properties": { "destination_types": { "items": { "$ref": "#/components/schemas/DestinationType" }, "title": "Destination Types", "type": "array" } }, "required": [ "destination_types" ], "title": "DestinationTypesResponse", "type": "object" }, "HealthResponse": { "description": "GET /v1/health (routers.health.health)", "properties": { "status": { "examples": [ "ok" ], "title": "Status", "type": "string" }, "version": { "examples": [ "0.1.0" ], "title": "Version", "type": "string" } }, "required": [ "status", "version" ], "title": "HealthResponse", "type": "object" }, "IsochroneAssumptions": { "additionalProperties": true, "description": "Routing assumptions echoed from the store. Keys are store-defined; the\ncurrent set is listed but extra keys are allowed. (routers.isochrone._assumptions)", "properties": { "max_trip_duration_min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "examples": [ 60 ], "title": "Max Trip Duration Min" }, "transit_departure": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "2026-07-15T08:00:00" ], "title": "Transit Departure" }, "transit_percentile": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "examples": [ 10 ], "title": "Transit Percentile" }, "transit_window_min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "examples": [ 60 ], "title": "Transit Window Min" } }, "title": "IsochroneAssumptions", "type": "object" }, "IsochroneBlock": { "properties": { "geoid": { "title": "Geoid", "type": "string" }, "travel_min": { "title": "Travel Min", "type": "integer" } }, "required": [ "geoid", "travel_min" ], "title": "IsochroneBlock", "type": "object" }, "IsochroneBlocks": { "description": "GET /v1/isochrone?format=blocks (routers.isochrone._blocks_body).", "properties": { "assumptions": { "$ref": "#/components/schemas/IsochroneAssumptions" }, "block": { "title": "Block", "type": "string" }, "blocks": { "items": { "$ref": "#/components/schemas/IsochroneBlock" }, "title": "Blocks", "type": "array" }, "direction": { "title": "Direction", "type": "string" }, "mode": { "title": "Mode", "type": "string" }, "reachable_blocks": { "title": "Reachable Blocks", "type": "integer" }, "v": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "V" }, "version": { "title": "Version", "type": "string" } }, "required": [ "blocks", "reachable_blocks", "block", "direction", "mode", "version", "assumptions" ], "title": "IsochroneBlocks", "type": "object" }, "IsochroneFeature": { "properties": { "geometry": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "GeoJSON geometry, or null when the contour is empty", "title": "Geometry" }, "properties": { "$ref": "#/components/schemas/IsochroneFeatureProperties" }, "type": { "examples": [ "Feature" ], "title": "Type", "type": "string" } }, "required": [ "type", "properties" ], "title": "IsochroneFeature", "type": "object" }, "IsochroneFeatureProperties": { "properties": { "contour": { "description": "Contour level in minutes", "title": "Contour", "type": "integer" }, "mode": { "title": "Mode", "type": "string" }, "reachable_blocks": { "title": "Reachable Blocks", "type": "integer" } }, "required": [ "contour", "mode", "reachable_blocks" ], "title": "IsochroneFeatureProperties", "type": "object" }, "IsochroneGeoJSON": { "description": "GET /v1/isochrone?format=geojson (routers.isochrone._geojson_body).\nFeatures are ordered largest contour first (painter's order).", "properties": { "assumptions": { "$ref": "#/components/schemas/IsochroneAssumptions" }, "block": { "description": "15-digit origin/destination block GEOID", "title": "Block", "type": "string" }, "direction": { "description": "'to' or 'from'", "title": "Direction", "type": "string" }, "features": { "items": { "$ref": "#/components/schemas/IsochroneFeature" }, "title": "Features", "type": "array" }, "mode": { "title": "Mode", "type": "string" }, "type": { "examples": [ "FeatureCollection" ], "title": "Type", "type": "string" }, "v": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Echoed cache-buster, when supplied", "title": "V" }, "version": { "description": "Store version key", "title": "Version", "type": "string" } }, "required": [ "type", "features", "block", "direction", "mode", "version", "assumptions" ], "title": "IsochroneGeoJSON", "type": "object" }, "IsochroneMetaResponse": { "description": "GET /v1/isochrone/meta (routers.isochrone.get_isochrone_meta)", "properties": { "assumptions": { "$ref": "#/components/schemas/IsochroneAssumptions" }, "dest_set": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dest Set" }, "directions": { "examples": [ [ "to", "from" ] ], "items": { "type": "string" }, "title": "Directions", "type": "array" }, "max_minutes": { "examples": [ 60 ], "title": "Max Minutes", "type": "integer" }, "modes": { "examples": [ [ "walk", "bike", "transit" ] ], "items": { "type": "string" }, "title": "Modes", "type": "array" }, "version": { "title": "Version", "type": "string" } }, "required": [ "version", "directions", "modes", "max_minutes", "assumptions" ], "title": "IsochroneMetaResponse", "type": "object" }, "LastUpdatedResponse": { "description": "GET /v1/last-updated (routers.meta.last_updated)", "properties": { "last_updated": { "description": "ISO-8601 timestamp of the newest published component", "examples": [ "2026-07-01T00:00:00+00:00" ], "title": "Last Updated", "type": "string" } }, "required": [ "last_updated" ], "title": "LastUpdatedResponse", "type": "object" }, "ModeItem": { "description": "One travel mode. (routers.meta._modes)", "properties": { "description": { "examples": [ "Walking" ], "title": "Description", "type": "string" }, "mode": { "description": "Short label", "examples": [ "walk" ], "title": "Mode", "type": "string" }, "mode_id": { "title": "Mode Id", "type": "integer" } }, "required": [ "mode_id", "mode", "description" ], "title": "ModeItem", "type": "object" }, "ModesResponse": { "properties": { "modes": { "items": { "$ref": "#/components/schemas/ModeItem" }, "title": "Modes", "type": "array" } }, "required": [ "modes" ], "title": "ModesResponse", "type": "object" }, "Place": { "description": "A census place (city/town) matched by name, with its GEOID and WGS84\ncentroid. (routers.places.places)", "properties": { "geoid": { "description": "Census place GEOID", "title": "Geoid", "type": "string" }, "lat": { "description": "Centroid latitude (WGS84)", "title": "Lat", "type": "number" }, "lon": { "description": "Centroid longitude (WGS84)", "title": "Lon", "type": "number" }, "name": { "title": "Name", "type": "string" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Two-letter USPS state abbreviation (e.g. 'RI')", "title": "State" } }, "required": [ "name", "geoid", "lon", "lat" ], "title": "Place", "type": "object" }, "PlacesResponse": { "properties": { "places": { "items": { "$ref": "#/components/schemas/Place" }, "title": "Places", "type": "array" } }, "required": [ "places" ], "title": "PlacesResponse", "type": "object" }, "PoiDetail": { "description": "GET /v1/pois/{dest_id} (queries.pois.detail)", "properties": { "address": { "$ref": "#/components/schemas/Address" }, "attrs": { "additionalProperties": true, "description": "Whitelisted attributes (currently only 'brand', when present)", "title": "Attrs", "type": "object" }, "dest_id": { "title": "Dest Id", "type": "integer" }, "lat": { "title": "Lat", "type": "number" }, "lon": { "title": "Lon", "type": "number" }, "name": { "title": "Name", "type": "string" }, "type_ids": { "items": { "type": "integer" }, "title": "Type Ids", "type": "array" } }, "required": [ "dest_id", "name", "lon", "lat", "address", "type_ids", "attrs" ], "title": "PoiDetail", "type": "object" }, "PoiSearchResponse": { "properties": { "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque keyset cursor; null on the last page", "title": "Next Cursor" }, "results": { "items": { "$ref": "#/components/schemas/PoiSearchResult" }, "title": "Results", "type": "array" } }, "required": [ "results" ], "title": "PoiSearchResponse", "type": "object" }, "PoiSearchResult": { "description": "A POI search hit. NOTE: no mode/travel_time here (search is spatial, not\nrouted). (routers.pois.poi_search)", "properties": { "address": { "$ref": "#/components/schemas/Address" }, "dest_id": { "title": "Dest Id", "type": "integer" }, "lat": { "title": "Lat", "type": "number" }, "lon": { "title": "Lon", "type": "number" }, "name": { "title": "Name", "type": "string" } }, "required": [ "dest_id", "name", "lon", "lat", "address" ], "title": "PoiSearchResult", "type": "object" }, "PoiTime": { "description": "One POI reachable from an origin, with its travel time. (shape.shape_pois)", "properties": { "address": { "$ref": "#/components/schemas/Address" }, "dest_id": { "title": "Dest Id", "type": "integer" }, "lat": { "title": "Lat", "type": "number" }, "lon": { "title": "Lon", "type": "number" }, "mode": { "title": "Mode", "type": "string" }, "name": { "title": "Name", "type": "string" }, "travel_time": { "description": "Minutes, capped at 30, 1 decimal", "title": "Travel Time", "type": "number" } }, "required": [ "dest_id", "mode", "travel_time", "name", "lon", "lat", "address" ], "title": "PoiTime", "type": "object" }, "PointPoisResponse": { "description": "GET /v1/point/pois (routers.point.point_pois)", "properties": { "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "resolved_block": { "title": "Resolved Block", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/PoiTime" }, "title": "Results", "type": "array" } }, "required": [ "resolved_block", "results" ], "title": "PointPoisResponse", "type": "object" }, "PointSummaryResponse": { "description": "GET /v1/point/summary (routers.point.point_summary)", "properties": { "block": { "$ref": "#/components/schemas/BlockMeta" }, "resolved_block": { "description": "GEOID of the block containing the point", "title": "Resolved Block", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/CategoryTime" }, "title": "Results", "type": "array" } }, "required": [ "resolved_block", "block", "results" ], "title": "PointSummaryResponse", "type": "object" }, "Problem": { "additionalProperties": true, "description": "RFC 9457 problem detail. Served as `application/problem+json`. Additional\nmembers appear for some problem types (e.g. `errors`). (core.problems.problem)", "properties": { "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" }, "status": { "title": "Status", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "type": { "description": "Problem type URI; the final path segment is the stable slug", "examples": [ "https://api.close.city/problems/not-found" ], "title": "Type", "type": "string" } }, "required": [ "type", "title", "status" ], "title": "Problem", "type": "object" }, "ValidationErrorItem": { "properties": { "loc": { "items": {}, "title": "Loc", "type": "array" }, "msg": { "title": "Msg", "type": "string" }, "type": { "title": "Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationErrorItem", "type": "object" }, "ValidationProblem": { "additionalProperties": true, "description": "400 invalid-parameters, carrying the offending fields.\n(core.problems, RequestValidationError handler)", "properties": { "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" }, "errors": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "type": "array" }, { "type": "null" } ], "title": "Errors" }, "status": { "title": "Status", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "type": { "description": "Problem type URI; the final path segment is the stable slug", "examples": [ "https://api.close.city/problems/not-found" ], "title": "Type", "type": "string" } }, "required": [ "type", "title", "status" ], "title": "ValidationProblem", "type": "object" }, "VintageComponent": { "description": "One dataset component's active version. (routers.meta.meta_vintage)", "properties": { "component": { "description": "road_network | transit_network | pois | blocks | parks", "title": "Component", "type": "string" }, "effective_date": { "description": "ISO date", "examples": [ "2026-05-01" ], "title": "Effective Date", "type": "string" }, "version": { "title": "Version", "type": "string" } }, "required": [ "component", "version", "effective_date" ], "title": "VintageComponent", "type": "object" }, "VintageResponse": { "properties": { "components": { "items": { "$ref": "#/components/schemas/VintageComponent" }, "title": "Components", "type": "array" } }, "required": [ "components" ], "title": "VintageResponse", "type": "object" } }, "securitySchemes": { "apiKey": { "description": "API key as a Bearer token. Create a free key at https://account.close.city (5,000 free tokens on signup, no card). Agents can complete sign-up programmatically — see https://docs.close.city.", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "name": "Close", "url": "https://close.city/" }, "description": "Travel times from every US census block to nearby points of interest, by walking,\nbiking, and public transit — the data behind [close.city](https://close.city).\nRead-only, and metered by returned rows.\n\n**Base URL:** `https://api.close.city`\n\n## Authentication\n\nMetered routes need an API key (`ck_live_…`), sent as a bearer token and created\nat [account.close.city](https://account.close.city). The catalog routes\n(`/v1/health`, `/v1/last-updated`, `/v1/meta/*`, `/v1/places`,\n`/v1/isochrone/meta`) are free and need no key.\n\n```\nAuthorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n```\n\n## Metering\n\nOne token is charged per returned data row (minimum one per request); the\nisochrone charges 10 tokens per contour level instead. A `304 Not Modified`\ncosts nothing. Every metered response carries `X-Tokens-Charged` and\n`X-Tokens-Remaining`.\n\n## Pagination & conditional requests\n\nList endpoints use opaque, signed keyset cursors — pass `limit`, then follow\n`next_cursor`. Metered `GET`s return an `ETag`; send it back as `If-None-Match`\nto revalidate for free.\n\n## Errors\n\nErrors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `problem+json`; the\nstable key is the final path segment of `type` (the slug, e.g.\n`tokens-exhausted`).\n\nSDKs: a [Python](https://docs.close.city/sdks/python/) and an\n[R](https://docs.close.city/sdks/r/) client wrap all of this.\n", "title": "Close API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/blocks/query": { "post": { "description": "Per-block travel times for every block intersecting a GeoJSON polygon, or\na radius around a point. One row per (block, category, mode).", "operationId": "blocks_query_v1_blocks_query_post", "requestBody": { "content": { "application/json": { "example": { "center": { "lat": 44.05, "lon": -123.09 }, "include_population": true, "mode": [ "walk" ], "radius_m": 1500, "type": [ 30 ] }, "schema": { "$ref": "#/components/schemas/BlocksQuery" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "next_cursor": null, "results": [ { "dest_type_id": 30, "geoid": "410390020001010", "mode_id": 1, "population": 1187, "travel_time": 6.5 } ] }, "schema": { "$ref": "#/components/schemas/ArealBlocksResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "Blocks within a polygon or radius", "tags": [ "areal" ] } }, "/v1/blocks/{geoid}/pois": { "get": { "description": "Every nearby point of interest and its travel time from this block,\none row per (POI, mode). Keyset-paginated by (mode, dest_id).", "operationId": "blocks_pois_v1_blocks__geoid__pois_get", "parameters": [ { "description": "15-digit census block GEOID", "in": "path", "name": "geoid", "required": true, "schema": { "description": "15-digit census block GEOID", "examples": [ "360610001001000" ], "pattern": "^\\d{15}$", "title": "Geoid", "type": "string" } }, { "in": "query", "name": "mode", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Mode" } }, { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Type" } }, { "in": "query", "name": "dest_id", "required": false, "schema": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Dest Id" } }, { "in": "query", "name": "max_minutes", "required": false, "schema": { "anyOf": [ { "maximum": 30, "minimum": 0, "type": "number" }, { "type": "null" } ], "title": "Max Minutes" } }, { "in": "query", "name": "limit", "required": false, "schema": { "anyOf": [ { "maximum": 1000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "example": { "block_geoid": "410390020001010", "next_cursor": "eyJhIjoxLCJiIjo5MDAxLCJ2IjoxfQ.Xa1b2c3d", "results": [ { "address": { "city": "Springfield", "state": "OR", "street": "742 Evergreen Ter", "zip": "97477" }, "dest_id": 9001, "lat": 44.05, "lon": -123.09, "mode": "walk", "name": "Market of Choice", "travel_time": 6.5 } ] }, "schema": { "$ref": "#/components/schemas/BlockPoisResponse" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Resource not found (block-not-found, poi-not-found, place-not-found, point-not-covered, no-isochrone-data, direction-not-available)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "Per-POI travel times", "tags": [ "origin block" ] } }, "/v1/blocks/{geoid}/summary": { "get": { "description": "Fastest travel time from this block to each destination category, by\nmode — the same per-category minimums close.city shows.", "operationId": "blocks_summary_v1_blocks__geoid__summary_get", "parameters": [ { "description": "15-digit census block GEOID", "in": "path", "name": "geoid", "required": true, "schema": { "description": "15-digit census block GEOID", "examples": [ "360610001001000" ], "pattern": "^\\d{15}$", "title": "Geoid", "type": "string" } }, { "in": "query", "name": "mode", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Mode" } }, { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Type" } } ], "responses": { "200": { "content": { "application/json": { "example": { "block": { "geoid": "410390020001010", "land_area_m2": 183245.0, "population": 1187 }, "results": [ { "dest_type_id": 30, "mode": "walk", "travel_time": 6.5 }, { "dest_type_id": 30, "mode": "transit", "travel_time": 11.0 } ] }, "schema": { "$ref": "#/components/schemas/BlockSummaryResponse" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Resource not found (block-not-found, poi-not-found, place-not-found, point-not-covered, no-isochrone-data, direction-not-available)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "Per-category travel times", "tags": [ "origin block" ] } }, "/v1/health": { "get": { "description": "Unauthenticated liveness probe. Touches no database and is never metered.", "operationId": "health_v1_health_get", "responses": { "200": { "content": { "application/json": { "example": { "status": "ok", "version": "0.1.0" }, "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "description": "Successful Response" } }, "summary": "Liveness check", "tags": [ "service" ] } }, "/v1/isochrone": { "get": { "description": "Travel-time contours around a census block (by GEOID) or a lat/lon point.\nSupply `block` XOR `lon`+`lat`, and `minutes` XOR `contours` (up to 4\nascending levels). `format=geojson` returns contour polygons (largest first);\n`format=blocks` returns the reachable blocks with their travel minutes.\nMetered at 10 tokens per contour level with a `ck_` key; unmetered for a Close+\nmember `mt_` bearer.", "operationId": "get_isochrone_v1_isochrone_get", "parameters": [ { "description": "15-digit census block GEOID", "in": "query", "name": "block", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "15-digit census block GEOID", "title": "Block" } }, { "description": "Longitude (WGS84)", "in": "query", "name": "lon", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude (WGS84)", "title": "Lon" } }, { "description": "Latitude (WGS84)", "in": "query", "name": "lat", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude (WGS84)", "title": "Lat" } }, { "description": "walk | bike | transit", "in": "query", "name": "mode", "required": false, "schema": { "default": "walk", "description": "walk | bike | transit", "title": "Mode", "type": "string" } }, { "description": "to | from", "in": "query", "name": "direction", "required": false, "schema": { "default": "to", "description": "to | from", "title": "Direction", "type": "string" } }, { "description": "Single threshold, 1-60", "in": "query", "name": "minutes", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Single threshold, 1-60", "title": "Minutes" } }, { "description": "Up to 4 ascending thresholds, e.g. 15,30,45", "in": "query", "name": "contours", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Up to 4 ascending thresholds, e.g. 15,30,45", "title": "Contours" } }, { "description": "geojson | blocks", "in": "query", "name": "format", "required": false, "schema": { "default": "geojson", "description": "geojson | blocks", "title": "Format", "type": "string" } }, { "description": "Opaque CDN cache-buster; echoed", "in": "query", "name": "v", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque CDN cache-buster; echoed", "title": "V" } } ], "responses": { "200": { "content": { "application/json": { "example": { "assumptions": { "max_trip_duration_min": 60, "transit_departure": "2026-07-15T08:00:00", "transit_percentile": 10, "transit_window_min": 60 }, "block": "410390020001010", "direction": "to", "features": [ { "geometry": { "coordinates": [ [ [ -123.1, 44.0 ], [ -123.0, 44.0 ], [ -123.0, 44.1 ], [ -123.1, 44.0 ] ] ], "type": "Polygon" }, "properties": { "contour": 30, "mode": "walk", "reachable_blocks": 128 }, "type": "Feature" } ], "mode": "walk", "type": "FeatureCollection", "version": "rn1_tn34" }, "schema": { "anyOf": [ { "$ref": "#/components/schemas/IsochroneGeoJSON" }, { "$ref": "#/components/schemas/IsochroneBlocks" } ], "title": "Response 200 Get Isochrone V1 Isochrone Get" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Resource not found (block-not-found, poi-not-found, place-not-found, point-not-covered, no-isochrone-data, direction-not-available)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "Travel-time contours from a block or point", "tags": [ "isochrone" ] } }, "/v1/isochrone/meta": { "get": { "description": "The active store version and its assumptions.\n\nThe frontend reads this for attribution, for the `v=` cache key, and to\nlearn which directions/modes actually exist rather than assuming.", "operationId": "get_isochrone_meta_v1_isochrone_meta_get", "responses": { "200": { "content": { "application/json": { "example": { "assumptions": { "max_trip_duration_min": 60, "transit_departure": "2026-07-15T08:00:00", "transit_percentile": 10, "transit_window_min": 60 }, "dest_set": "bb_pairs/all", "directions": [ "to", "from" ], "max_minutes": 60, "modes": [ "walk", "bike", "transit" ], "version": "rn1_tn34" }, "schema": { "$ref": "#/components/schemas/IsochroneMetaResponse" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "summary": "Isochrone store version and assumptions", "tags": [ "isochrone" ] } }, "/v1/last-updated": { "get": { "description": "Publication timestamp of the most recent public dataset component. Free\n(no API key required).", "operationId": "last_updated_v1_last_updated_get", "responses": { "200": { "content": { "application/json": { "example": { "last_updated": "2026-07-01T00:00:00+00:00" }, "schema": { "$ref": "#/components/schemas/LastUpdatedResponse" } } }, "description": "Successful Response" } }, "summary": "Newest data timestamp", "tags": [ "metadata" ] } }, "/v1/meta/destination-types": { "get": { "description": "The destination-type taxonomy. Parent types carry the leaf ids they\nexpand to when used as a travel-time `type` filter. Free and cached.", "operationId": "meta_destination_types_v1_meta_destination_types_get", "responses": { "200": { "content": { "application/json": { "example": { "destination_types": [ { "dest_type_id": 1, "is_leaf": false, "label": "Public schools", "leaf_ids": [ 5, 6, 7 ], "name": "schools_public" }, { "dest_type_id": 30, "is_leaf": true, "label": "Grocery stores", "leaf_ids": [ 30 ], "name": "grocery" } ] }, "schema": { "$ref": "#/components/schemas/DestinationTypesResponse" } } }, "description": "Successful Response" } }, "summary": "Destination-type taxonomy", "tags": [ "metadata" ] } }, "/v1/meta/modes": { "get": { "description": "The travel modes and their numeric ids. Free and container-cached.", "operationId": "meta_modes_v1_meta_modes_get", "responses": { "200": { "content": { "application/json": { "example": { "modes": [ { "description": "Walking", "mode": "walk", "mode_id": 1 }, { "description": "Biking", "mode": "bike", "mode_id": 2 }, { "description": "Public transit", "mode": "transit", "mode_id": 3 } ] }, "schema": { "$ref": "#/components/schemas/ModesResponse" } } }, "description": "Successful Response" } }, "summary": "List travel modes", "tags": [ "metadata" ] } }, "/v1/meta/vintage": { "get": { "description": "The active version and effective date of each dataset component\n(road network, transit, POIs, blocks, parks). Free and cached.", "operationId": "meta_vintage_v1_meta_vintage_get", "responses": { "200": { "content": { "application/json": { "example": { "components": [ { "component": "road_network", "effective_date": "2026-03-18", "version": "osm-2026-03" }, { "component": "transit_network", "effective_date": "2026-07-13", "version": "gtfs-2026-07" } ] }, "schema": { "$ref": "#/components/schemas/VintageResponse" } } }, "description": "Successful Response" } }, "summary": "Dataset component versions", "tags": [ "metadata" ] } }, "/v1/places": { "get": { "description": "Resolve a city/town name to its census place GEOID and WGS84 centroid.\nFree (no API key). Matches are ranked prefix-first, then by population. Feed\n`lon`/`lat` into `/v1/blocks/query` (center + radius_m), or `geoid` into\n`/v1/places/{geoid}/blocks`.", "operationId": "places_v1_places_get", "parameters": [ { "description": "Name substring, e.g. 'Providence'", "in": "query", "name": "q", "required": true, "schema": { "description": "Name substring, e.g. 'Providence'", "maxLength": 80, "minLength": 2, "title": "Q", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "maximum": 20, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacesResponse" } } }, "description": "Successful Response" } }, "summary": "Search census places by name", "tags": [ "places" ] } }, "/v1/places/{geoid}/blocks": { "get": { "description": "Per-block travel times for every census block in a place (city/town).", "operationId": "place_blocks_v1_places__geoid__blocks_get", "parameters": [ { "description": "Census place GEOID", "in": "path", "name": "geoid", "required": true, "schema": { "description": "Census place GEOID", "title": "Geoid", "type": "string" } }, { "in": "query", "name": "mode", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Mode" } }, { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Type" } }, { "in": "query", "name": "include_population", "required": false, "schema": { "default": false, "title": "Include Population", "type": "boolean" } }, { "in": "query", "name": "limit", "required": false, "schema": { "anyOf": [ { "maximum": 1000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "example": { "next_cursor": null, "results": [ { "dest_type_id": 30, "geoid": "410390020001010", "mode_id": 1, "travel_time": 6.5 } ] }, "schema": { "$ref": "#/components/schemas/ArealBlocksResponse" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Resource not found (block-not-found, poi-not-found, place-not-found, point-not-covered, no-isochrone-data, direction-not-available)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "Blocks within a census place", "tags": [ "areal" ] } }, "/v1/places/{geoid}/pois": { "get": { "description": "Every point of interest whose location falls within a census place's\nboundary (city/town). The place analog of `/v1/pois`; filter by `type` to\nget, e.g., all supermarkets in a city. Spatial only — no travel times.", "operationId": "place_pois_v1_places__geoid__pois_get", "parameters": [ { "description": "Census place GEOID", "in": "path", "name": "geoid", "required": true, "schema": { "description": "Census place GEOID", "title": "Geoid", "type": "string" } }, { "description": "Destination type id(s) to keep", "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "description": "Destination type id(s) to keep", "title": "Type" } }, { "description": "Name substring", "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name substring", "title": "Q" } }, { "in": "query", "name": "limit", "required": false, "schema": { "anyOf": [ { "maximum": 1000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "example": { "next_cursor": null, "results": [ { "address": { "city": "Springfield", "state": "OR", "street": "742 Evergreen Ter", "zip": "97477" }, "dest_id": 9001, "lat": 44.05, "lon": -123.09, "name": "Market of Choice" } ] }, "schema": { "$ref": "#/components/schemas/PoiSearchResponse" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Resource not found (block-not-found, poi-not-found, place-not-found, point-not-covered, no-isochrone-data, direction-not-available)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "POIs within a census place", "tags": [ "areal" ] } }, "/v1/point/pois": { "get": { "description": "Every nearby POI and its travel time from the census block containing this\nlat/lon, one row per (POI, mode). Keyset-paginated by (mode, dest_id).", "operationId": "point_pois_v1_point_pois_get", "parameters": [ { "description": "Latitude (WGS84)", "in": "query", "name": "lat", "required": true, "schema": { "description": "Latitude (WGS84)", "maximum": 90, "minimum": -90, "title": "Lat", "type": "number" } }, { "description": "Longitude (WGS84)", "in": "query", "name": "lon", "required": true, "schema": { "description": "Longitude (WGS84)", "maximum": 180, "minimum": -180, "title": "Lon", "type": "number" } }, { "in": "query", "name": "mode", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Mode" } }, { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Type" } }, { "in": "query", "name": "dest_id", "required": false, "schema": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Dest Id" } }, { "in": "query", "name": "max_minutes", "required": false, "schema": { "anyOf": [ { "maximum": 30, "minimum": 0, "type": "number" }, { "type": "null" } ], "title": "Max Minutes" } }, { "in": "query", "name": "limit", "required": false, "schema": { "anyOf": [ { "maximum": 1000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "example": { "next_cursor": null, "resolved_block": "410390020001010", "results": [ { "address": { "city": "Springfield", "state": "OR", "street": "742 Evergreen Ter", "zip": "97477" }, "dest_id": 9001, "lat": 44.05, "lon": -123.09, "mode": "walk", "name": "Market of Choice", "travel_time": 6.5 } ] }, "schema": { "$ref": "#/components/schemas/PointPoisResponse" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Resource not found (block-not-found, poi-not-found, place-not-found, point-not-covered, no-isochrone-data, direction-not-available)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "Per-POI travel times at a point", "tags": [ "origin coordinate" ] } }, "/v1/point/summary": { "get": { "description": "Fastest travel time to each destination category by mode, from the census\nblock containing this lat/lon. Same shape as `/v1/blocks/{geoid}/summary`,\nwith the resolved block GEOID echoed as `resolved_block`.", "operationId": "point_summary_v1_point_summary_get", "parameters": [ { "description": "Latitude (WGS84)", "in": "query", "name": "lat", "required": true, "schema": { "description": "Latitude (WGS84)", "maximum": 90, "minimum": -90, "title": "Lat", "type": "number" } }, { "description": "Longitude (WGS84)", "in": "query", "name": "lon", "required": true, "schema": { "description": "Longitude (WGS84)", "maximum": 180, "minimum": -180, "title": "Lon", "type": "number" } }, { "in": "query", "name": "mode", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Mode" } }, { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Type" } } ], "responses": { "200": { "content": { "application/json": { "example": { "block": { "geoid": "410390020001010", "land_area_m2": 183245.0, "population": 1187 }, "resolved_block": "410390020001010", "results": [ { "dest_type_id": 30, "mode": "walk", "travel_time": 6.5 } ] }, "schema": { "$ref": "#/components/schemas/PointSummaryResponse" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Resource not found (block-not-found, poi-not-found, place-not-found, point-not-covered, no-isochrone-data, direction-not-available)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "Per-category travel times at a point", "tags": [ "origin coordinate" ] } }, "/v1/pois": { "get": { "description": "Find POIs within a bounding box or a radius of a point. Provide either\n`bbox`, or `lat`+`lon`+`radius_m`.", "operationId": "poi_search_v1_pois_get", "parameters": [ { "in": "query", "name": "lat", "required": false, "schema": { "anyOf": [ { "maximum": 90, "minimum": -90, "type": "number" }, { "type": "null" } ], "title": "Lat" } }, { "in": "query", "name": "lon", "required": false, "schema": { "anyOf": [ { "maximum": 180, "minimum": -180, "type": "number" }, { "type": "null" } ], "title": "Lon" } }, { "in": "query", "name": "radius_m", "required": false, "schema": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 50000, "type": "number" }, { "type": "null" } ], "title": "Radius M" } }, { "description": "min_lon,min_lat,max_lon,max_lat", "in": "query", "name": "bbox", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "min_lon,min_lat,max_lon,max_lat", "title": "Bbox" } }, { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Type" } }, { "description": "Name substring", "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name substring", "title": "Q" } }, { "in": "query", "name": "limit", "required": false, "schema": { "anyOf": [ { "maximum": 1000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "example": { "next_cursor": null, "results": [ { "address": { "city": "Springfield", "state": "OR", "street": "742 Evergreen Ter", "zip": "97477" }, "dest_id": 9001, "lat": 44.05, "lon": -123.09, "name": "Market of Choice" } ] }, "schema": { "$ref": "#/components/schemas/PoiSearchResponse" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "Search POIs by location", "tags": [ "destination POI" ] } }, "/v1/pois/{dest_id}": { "get": { "description": "Name, location, address, types, and whitelisted attributes for one POI.", "operationId": "poi_detail_v1_pois__dest_id__get", "parameters": [ { "description": "Stable destination id", "in": "path", "name": "dest_id", "required": true, "schema": { "description": "Stable destination id", "examples": [ 4181 ], "title": "Dest Id", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "address": { "city": "Springfield", "state": "OR", "street": "742 Evergreen Ter", "zip": "97477" }, "attrs": { "brand": "Market of Choice" }, "dest_id": 9001, "lat": 44.05, "lon": -123.09, "name": "Market of Choice", "type_ids": [ 30 ] }, "schema": { "$ref": "#/components/schemas/PoiDetail" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Resource not found (block-not-found, poi-not-found, place-not-found, point-not-covered, no-isochrone-data, direction-not-available)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "POI detail", "tags": [ "destination POI" ] } }, "/v1/pois/{dest_id}/catchment": { "get": { "description": "Every census block within reach of this POI and its travel time, one row\nper (block, mode). Keyset-paginated by (mode, block).", "operationId": "poi_catchment_v1_pois__dest_id__catchment_get", "parameters": [ { "description": "Stable destination id", "in": "path", "name": "dest_id", "required": true, "schema": { "description": "Stable destination id", "examples": [ 4181 ], "title": "Dest Id", "type": "integer" } }, { "in": "query", "name": "mode", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Mode" } }, { "in": "query", "name": "block", "required": false, "schema": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Block" } }, { "in": "query", "name": "max_minutes", "required": false, "schema": { "anyOf": [ { "maximum": 30, "minimum": 0, "type": "number" }, { "type": "null" } ], "title": "Max Minutes" } }, { "in": "query", "name": "limit", "required": false, "schema": { "anyOf": [ { "maximum": 1000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "example": { "dest_id": 9001, "next_cursor": null, "results": [ { "geoid": "410390020001010", "mode": "walk", "travel_time": 6.5 } ] }, "schema": { "$ref": "#/components/schemas/CatchmentResponse" } } }, "description": "Successful Response" }, "304": { "description": "Not modified (If-None-Match matched the ETag); no body, no tokens charged" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } }, "description": "Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex)" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing or invalid API key (missing-key, invalid-key)" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Key disabled (account-disabled)" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Resource not found (block-not-found, poi-not-found, place-not-found, point-not-covered, no-isochrone-data, direction-not-available)" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After" } }, "security": [ { "apiKey": [] } ], "summary": "Blocks that can reach a POI", "tags": [ "destination POI" ] } } }, "servers": [ { "url": "https://api.close.city" } ], "tags": [ { "name": "service" }, { "name": "metadata" }, { "name": "places" }, { "name": "origin block" }, { "name": "origin coordinate" }, { "name": "destination POI" }, { "name": "areal" }, { "name": "isochrone" } ] }