Carris Metropolitana API

Free Lisbon metropolitan bus API with no key: lines, routes, patterns, stops, live vehicle positions and arrival estimates across 15 municipalities. Tested example included.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the Carris Metropolitana API?

Carris Metropolitana publishes a free, key-free API for the bus network serving the Lisbon metropolitan area. It exposes lines with their colours and municipalities, route patterns, stops, live vehicle positions and real-time arrival estimates, all as plain JSON.

When the Lisbon metropolitan area reorganised its suburban bus network in 2022 it built the open API alongside the service rather than years later, and it shows. Endpoints are flat and predictable, identifiers are stable, and the same line id works across the static and real-time sides — so a stop's arrival estimates join to its line record without a translation table.

The data model separates three things that transit APIs often conflate. A `line` is the brand a passenger recognises, a `route` is a direction of that line, and a `pattern` is one specific sequence of stops within a route — which is how variants that skip a stretch or terminate early are represented without inventing new line numbers. Line 1001 in the example carries two patterns under one route. The `color` and `text_color` pair gives you the official badge colours directly, so a rendered line number matches the printed timetable.

Quick facts

Base URL: https://api.carrismetropolitana.pt
Authentication: No key or account. Open data published by the operator for the Lisbon metropolitan transport authority.
Rate limit: No published quota. Real-time endpoints refresh every few seconds; static data changes only with timetable revisions.
Pricing: Free.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the Carris Metropolitana API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Fetch a bus line with its routes, patterns and localities

GET https://api.carrismetropolitana.pt/lines/1001

curl

curl 'https://api.carrismetropolitana.pt/lines/1001'

JavaScript (fetch)

const res = await fetch("https://api.carrismetropolitana.pt/lines/1001");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://api.carrismetropolitana.pt/lines/1001", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200

{
  "color": "#C61D23",
  "facilities": [],
  "id": "1001",
  "localities": [
    "Alfragide",
    "Amadora",
    "Reboleira",
    "Buraca"
  ],
  "long_name": "Alfragide (Estr Seminario) - Reboleira (Estação)",
  "municipalities": [
    "1115"
  ],
  "patterns": [
    "1001_0_1",
    "1001_0_2"
  ],
  "routes": [
    "1001_0"
  ],
  "short_name": "1001",
  "text_color": "#FFFFFF"
}

Parameters

Parameter	Type	Required	Description
`(lines)`	path	Optional	`/lines` lists every line; `/lines/{id}` returns one. `1001`
`(routes)`	path	Optional	`/routes/{id}` returns a direction of a line. `1001_0`
`(patterns)`	path	Optional	`/patterns/{id}` returns one stop sequence with its schedule. `1001_0_1`
`(stops)`	path	Optional	`/stops` lists every stop with coordinates; `/stops/{id}` returns one. `060001`
`(realtime)`	path	Optional	`/stops/{id}/realtime` returns live arrival estimates for a stop. `realtime`
`(vehicles)`	path	Optional	`/vehicles` returns live positions for the whole fleet. `vehicles`

Response fields

idstring: Line identifier, such as "1001". It appears again as a prefix in route and pattern ids.
short_name / long_namestring: The number shown on the vehicle and the full route description with its endpoints.
color / text_colorstring: Official hex colours including the leading hash, so a rendered badge matches printed material.
localitiesarray: Named places the line serves, which is more useful for search than the municipality codes.
municipalitiesarray: Municipality codes the line passes through, for administrative filtering.
routesarray: Route ids belonging to this line — normally one per direction.
patternsarray: Pattern ids, one per distinct stop sequence. Variants that skip a section appear here rather than as separate lines.
facilitiesarray: Accessibility and interchange facilities associated with the line, often empty.

What you can build with the Carris Metropolitana API

Build a Lisbon-area bus route browser
Show live arrival estimates at a specific stop
Plot live vehicle positions on a map
Render line badges in the operator's official colours
Filter routes by municipality or locality for a local guide

Common errors and how to fix them

404 on a pattern id

Pattern ids are compound — line, direction and variant.

Fix: Read the `patterns` array from the line record rather than constructing ids. The format is `{line}_{direction}_{variant}`.

Empty realtime array at a stop

No vehicle is currently due within the prediction window.

Fix: Overnight and on Sundays many suburban routes do not run. Fall back to the pattern schedule for planned times.

Municipality codes are opaque

They are official Portuguese administrative codes, not names.

Fix: Use the `localities` array for anything user-facing, and resolve municipality codes against a Portuguese administrative dataset if you need names.

Colours applied without the hash

`color` already includes the leading `#`.

Fix: Do not prepend another one. A doubled hash silently produces an invalid CSS colour and a default-styled badge.

Carris Metropolitana API — frequently asked questions

Is the Carris Metropolitana API free?

Yes, free with no key or account. It is open data published by the operator for the Lisbon metropolitan area transport authority.

What is the difference between a line, a route and a pattern?

A line is the branded service a passenger recognises, a route is one direction of it, and a pattern is one specific stop sequence within that route. Variants that skip a section are patterns, not separate lines.

Does it include live vehicle positions?

Yes. The `/vehicles` endpoint returns live positions for the fleet, and `/stops/{id}/realtime` gives arrival estimates for a single stop.

Does it cover the Lisbon Metro or trams?

No. This is the metropolitan bus network across fifteen municipalities. The Metro and the historic trams are operated separately and publish their own data.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

CSV to GeoJSON Converter

Turn a CSV of coordinates into a GeoJSON FeatureCollection, picking the latitude and longitude columns and keeping every other column as a property.

JSON to CSV Converter

Convert a JSON array of objects to CSV online. Automatic column headers from the union of all keys, delimiter choice and proper quoting — all in-browser.

Carris Metropolitana is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.