Skip to content
Close API

Blocks within a polygon or radius

POST
/v1/blocks/query

Per-block travel times for every block intersecting a GeoJSON polygon, or a radius around a point. One row per (block, category, mode).

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
BlocksQuery
object
center
Any of:
Center
object
lat
required
Lat
number
>= -90 <= 90
lon
required
Lon
number
>= -180 <= 180
cursor
Any of:
string
include_population
Include Population
boolean
limit
Any of:
integer
>= 1 <= 1000
mode
Any of:
Array<string>
polygon
Any of:
object
key
additional properties
any
radius_m
Any of:
number
> 0 <= 28000
type
Any of:
Array<integer>
Example
{
  "center": {
    "lat": 44.05,
    "lon": -123.09
  },
  "include_population": true,
  "mode": [
    "walk"
  ],
  "radius_m": 1500,
  "type": [
    30
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

ArealBlocksResponse

POST /v1/blocks/query and GET /v1/places/{geoid}/blocks (routers.spatial._paged)

object
next_cursor
Any of:
string
results
required
Results
Array<object>
ArealBlockResult

One (block, category, mode) row. NOTE the int mode_id here, unlike the string mode on the block/point routes. (queries.spatial._pivot)

object
dest_type_id
required
Dest Type Id
integer
geoid
required
Geoid
string
mode_id
required
Mode Id

Numeric mode id (see /v1/meta/modes)

integer
population
Any of:
integer
travel_time
required
Travel Time

Minutes, 1 decimal

number
Example
{
  "next_cursor": null,
  "results": [
    {
      "dest_type_id": 30,
      "geoid": "410390020001010",
      "mode_id": 1,
      "population": 1187,
      "travel_time": 6.5
    }
  ]
}

400

Section titled “400”

Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex, missing-origins, too-many-origins)

ValidationProblem

400 invalid-parameters, carrying the offending fields. (core.problems, RequestValidationError handler)

object
detail
Any of:
string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc
Array
msg
required
Msg
string
type
required
Type
string
status
required
Status
integer
title
required
Title
string
type
required
Type

Problem type URI; the final path segment is the stable slug

string
key
additional properties
any

401

Section titled “401”

Missing or invalid API key (missing-key, invalid-key)

Problem

RFC 9457 problem detail. Served as application/problem+json. Additional members appear for some problem types (e.g. errors). (core.problems.problem)

object
detail
Any of:
string
status
required
Status
integer
title
required
Title
string
type
required
Type

Problem type URI; the final path segment is the stable slug

string
key
additional properties
any

403

Section titled “403”

Key disabled (account-disabled)

Problem

RFC 9457 problem detail. Served as application/problem+json. Additional members appear for some problem types (e.g. errors). (core.problems.problem)

object
detail
Any of:
string
status
required
Status
integer
title
required
Title
string
type
required
Type

Problem type URI; the final path segment is the stable slug

string
key
additional properties
any

429

Section titled “429”

Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After

Problem

RFC 9457 problem detail. Served as application/problem+json. Additional members appear for some problem types (e.g. errors). (core.problems.problem)

object
detail
Any of:
string
status
required
Status
integer
title
required
Title
string
type
required
Type

Problem type URI; the final path segment is the stable slug

string
key
additional properties
any

503

Section titled “503”

Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After

Problem

RFC 9457 problem detail. Served as application/problem+json. Additional members appear for some problem types (e.g. errors). (core.problems.problem)

object
detail
Any of:
string
status
required
Status
integer
title
required
Title
string
type
required
Type

Problem type URI; the final path segment is the stable slug

string
key
additional properties
any