API reference
Every public endpoint, built from our OpenAPI description. The SQL API, the open data files and the tracker feeds.
Get an API key
Section titled “Get an API key”The SQL API needs a free key. The data files and tracker feeds don’t.
- Go to transitlab.nyc/api-keys.
- Enter your email address and send the form. A bot check runs in the page; it never asks you anything.
- 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.
Send the key
Section titled “Send the key”Put the key in the Authorization header as a Bearer token:
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.
Base URLs
Section titled “Base URLs”| Host | Serves |
|---|---|
api.transitlab.nyc | The SQL API and the MCP server |
data.transitlab.nyc | The open data files: catalog, Parquet files, DuckDB database |
transitlab.nyc | The 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.
Errors
Section titled “Errors”The SQL API answers errors with JSON: a short error code and a message in plain words.
{ "error": "rate_limited", "message": "Too many requests: the limit is 60 a minute. Try again in 12 seconds."}| Status | Meaning |
|---|---|
| 400 | The request or the SQL is wrong. The message says what to fix. |
| 401 | No key, or one we don’t know or have turned off. |
| 404 | No such table, file or page. |
| 408 | The query ran past 30 seconds. |
| 413 | The body is too large. |
| 429 | Over a limit. Wait the Retry-After seconds. |
| 503 | The 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.
Rate limits
Section titled “Rate limits”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.
Endpoints
Section titled “Endpoints”SQL API
Read-only SQL on every open table, on api.transitlab.nyc. Free key required for SQL.
- GET
/v1/healthSQL API health - GET
/v1/tablesList tables - GET
/v1/tables/{name}Describe a table - POST
/v1/sqlRun a SQL query - POST
/mcpMCP server (streamable HTTP) - POST
/v1/feedbackReport a problem or a wish
Open data files
Catalog, Parquet files and DuckDB database on data.transitlab.nyc.
- GET
/v1/catalog.jsonOpen data catalog - GET
/v1/{table}.parquetDownload a small table as one Parquet file - GET
/v1/{table}/year={year}/month={month}/{file}.parquetDownload one month or day of a large table - GET
/v1/transitlab.duckdbDuckDB database with a view per table
Tracker feeds
Nightly JSON behind the trackers.