Skip to content
Close API

Per-category travel times for many blocks

POST
/v1/blocks/summary

Fastest travel time from each of many census blocks to each destination category, by mode. This is the batch form of GET /v1/blocks/{geoid}/summary. Each result row carries its origin geoid, and per-block population and land area come back in blocks. The whole batch counts as one request against the rate limit.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
BlockSummaryBatch
object
mode
Any of:
Array<string>
origins
required
Origins

Census block GEOIDs (1-250)

Array<string>
type
Any of:
Array<integer>
Example
{
  "mode": [
    "walk"
  ],
  "origins": [
    "410390020001010",
    "410390020001011"
  ],
  "type": [
    30
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

BatchBlockSummaryResponse

POST /v1/blocks/summary (routers.batch.blocks_summary_batch)

object
blocks
required
Blocks

Per-origin block metadata

Array<object>
BlockMeta

Census-block metadata. (queries.blocks.summary_rows -> block_meta)

object
geoid
required
Geoid

15-digit census block GEOID

string
land_area_m2
Any of:
number
population
Any of:
integer
errors
required
Errors
Array<object>
OriginError

One origin that could not be resolved in a batch call. Extra members carry the origin key: geoid (blocks), origin_lat/origin_lon (points), or dest_id (catchment). (routers.batch)

object
detail
required
Detail
string
type
required
Type

Error slug: block-not-found, no-block-data, point-not-covered, or poi-not-found

string
key
additional properties
any
results
required
Results
Array<object>
BatchBlockCategoryTime

A CategoryTime row tagged with its origin block. (routers.batch)

object
dest_type_id
required
Dest Type Id
integer
geoid
required
Geoid

Origin block GEOID

string
mode
required
Mode

Travel mode label, e.g. ‘walk’

string
travel_time
required
Travel Time

Minutes, capped at 30, 1 decimal

number
truncated
required
Truncated

Origin GEOIDs skipped once the row budget was spent

Array<string>
truncated_reason
Any of:
string
Example
{
  "blocks": [
    {
      "geoid": "410390020001010",
      "land_area_m2": 45120,
      "population": 1187
    },
    {
      "geoid": "410390020001011",
      "land_area_m2": 38210,
      "population": 902
    }
  ],
  "errors": [],
  "results": [
    {
      "dest_type_id": 30,
      "geoid": "410390020001010",
      "mode": "walk",
      "travel_time": 6.5
    },
    {
      "dest_type_id": 30,
      "geoid": "410390020001011",
      "mode": "walk",
      "travel_time": 9
    }
  ],
  "truncated": [],
  "truncated_reason": null
}

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