Skip to content
Docs

API reference

Every public endpoint, built from our OpenAPI description. The SQL API, the open data files and the tracker feeds.

The SQL API needs a free key. The data files and tracker feeds don’t.

  1. Go to transitlab.nyc/api-keys.
  2. Enter your email address and send the form. A bot check runs in the page; it never asks you anything.
  3. We email you the key from hello@transitlab.nyc. It starts with tl_live_.

We keep only a fingerprint of the key, so we can’t send it again. If you lose it, ask for a new one.

Put the key in the Authorization header as a Bearer token:

Terminal
curl https://api.transitlab.nyc/v1/sql -H "Authorization: Bearer $TRANSITLAB_API_KEY" -H "Content-Type: application/json" -d '{"sql": "select count(*) from bus_lanes"}'

POST /v1/sql and POST /mcp need a key. /v1/tables, /v1/health and /v1/feedback work with or without one. Keep the key out of code you share and out of pages that run in a browser: anyone who has it can spend its limits. The samples here read it from the TRANSITLAB_API_KEY environment variable.

HostServes
api.transitlab.nycThe SQL API and the MCP server
data.transitlab.nycThe open data files: catalog, Parquet files, DuckDB database
transitlab.nycThe tracker feeds: the nightly JSON behind the site’s trackers

All three are HTTPS only. Bodies are JSON unless a page says otherwise.

Every page here is built from openapi.json, the OpenAPI 3.1 description of the API. For a walk through the SQL API, with advice on queries that finish in time, read the SQL API guide.

The SQL API answers errors with JSON: a short error code and a message in plain words.

JSON
{
"error": "rate_limited",
"message": "Too many requests: the limit is 60 a minute. Try again in 12 seconds."
}
StatusMeaning
400The request or the SQL is wrong. The message says what to fix.
401No key, or one we don’t know or have turned off.
404No such table, file or page.
408The query ran past 30 seconds.
413The body is too large.
429Over a limit. Wait the Retry-After seconds.
503The engine is busy, starting, or out of engine time for the month. Wait the Retry-After seconds.

The SQL API guide lists every error code. /v1/feedback errors carry the same two fields, plus ok: false.

A free key allows 60 requests a minute, 1,000 queries and 5 minutes of query time a day, and two queries at once. Each query stops after 30 seconds and returns at most 10,000 rows. Every SQL API answer carries RateLimit-Policy and RateLimit headers, so a client can slow down before it hits a limit. The SQL API guide has the full table and explains the monthly engine cap.

The files on data.transitlab.nyc need no key. Large tables come as one file a month or a day, so fetch only the ones you need.

SQL API

Read-only SQL on every open table, on api.transitlab.nyc. Free key required for SQL.

Open data files

Catalog, Parquet files and DuckDB database on data.transitlab.nyc.

Tracker feeds

Nightly JSON behind the trackers.