Skip to content
Docs

Describe a table

One table's columns (name, type, meaning), source, license and file URLs.

GET https://api.transitlab.nyc/v1/tables/{name} Key optional

Partitioned tables also list the year and month columns to filter on. A key is optional.

curl https://api.transitlab.nyc/v1/tables/taxi_yellow_trips
import requests
r = requests.get(
"https://api.transitlab.nyc/v1/tables/taxi_yellow_trips",
timeout=60,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://api.transitlab.nyc/v1/tables/taxi_yellow_trips")
if (!res.ok) throw new Error(`HTTP ${res.status}`)
console.log(await res.json())

A key is optional. Without one, requests count against your IP address’s limits. With one, they count against the key’s.

  • name string path required

    A table name from GET /v1/tables.

The table.

  • name string required

    Table name, as written in SQL.

  • description string

    What a row is.

  • rows integer

    Row count.

  • bytes integer

    Total size of the table’s Parquet files.

  • files integer

    Number of Parquet files.

  • partitioned_by_year_month boolean

    True if the table is one file a month or a day, with year and month columns to filter on.

  • first_day string (date)

    First day covered (partitioned tables only).

  • last_day string (date)

    Last day covered (partitioned tables only).

  • source string

    Where the data comes from.

  • license string

    License of the table.

  • columns object[] required

    Columns with types and meanings, plus year and month on partitioned tables.

  • columns[].name string required

  • columns[].type string required

    DuckDB type, e.g. VARCHAR, DATE, BIGINT, DOUBLE.

  • columns[].description string required

  • file_urls string (uri)[] required

    The table’s Parquet files on data.transitlab.nyc.

Example
{
"name": "bus_lanes",
"description": "Stretches of bus route between two timepoint stops: speed, time lost to traffic, and how much has a bus lane.",
"rows": 4219,
"bytes": 152710,
"files": 1,
"partitioned_by_year_month": false,
"source": "MTA bus speeds between timepoints (data.ny.gov) and NYC DOT bus lanes, computed by TransitLab (notes/bus-lanes.md).",
"license": "CC BY 4.0",
"columns": [
{
"name": "route_id",
"type": "VARCHAR",
"description": "Bus route."
},
{
"name": "direction",
"type": "VARCHAR",
"description": "Direction letter (N, S, E, W)."
},
{
"name": "a_name",
"type": "VARCHAR",
"description": "Timepoint stop where the stretch starts."
}
],
"file_urls": ["https://data.transitlab.nyc/v1/bus_lanes.parquet"]
}
StatusWhen
404Not found. No such table.
429Too many requests. Too many requests.

Error responses carry this body:

  • error string required

    A short code: unauthorized, rate_limited, daily_queries, daily_compute, concurrency, busy, budget_exhausted, engine_unavailable, bad_sql, not_read_only, sql_error, not_allowed, timeout, out_of_memory, bad_format, bad_limit, bad_date, no_such_table, not_found.

  • message string required

    What went wrong and what to do, in plain words.

  • get_a_key string (uri)

    On 401: where to get a key.

  • docs string (uri)

    On 401: the API guide.

Example (404)
{
"error": "no_such_table",
"message": "No table named \"no_such\". GET /v1/tables lists them."
}