Getting Started

Welcome to WooshAPI, a highly performant unified real-time vehicle positioning database. This service ingests public transit feeds (including GTFS-RT, CSV, GraphQL, and WebSocket streams), normalizes their values, and serves them via REST, WebSockets, or GTFS-RT outputs.

To use the API, you must request an account and generate an API key from the Admin Panel.

Authentication

All REST calls (except carrier list) require an API key passed via the header or query parameter.

Headers

Authorization: Bearer wosh_your_api_key_here
X-API-Key: wosh_your_api_key_here

Query Parameter (Discouraged)

GET /api/v1/vehicles?api_key=wosh_your_api_key_here

List Carriers

Returns a list of all supported transit systems, their region metadata, and their real-time state statistics. No authentication required.

GET /api/v1/carriers

Sample Response

{
  "count": 24,
  "carriers": [
    {
      "id": "ee_harjumaa_tlt",
      "name": "Tallinn Urban Transit",
      "company": "TLT (Tallinna Linnatranspordi AS)",
      "country": "EE",
      "region": "Tallinn",
      "active_vehicles": 244,
      "last_update": 1786523910000,
      "status": "live"
    }
  ]
}

Fetch Vehicles

Retrieve active vehicle locations. You can filter by carrier, country, type, route, or radius.

GET /api/v1/vehicles

Query Parameters

Parameter	Type	Description
`carrier`	String	Comma-separated carrier IDs (e.g. `ee_harjumaa_tlt,ee_national_elron`)
`country`	String	Filter by ISO country code (e.g. `EE`, `LV`, `LT`, `FI`, `NL`)
`type`	String	Comma-separated types: `BUS`, `TRAM`, `TROLLEYBUS`, `TRAIN`, `SUBWAY`, `FERRY`, `MONORAIL`
`route`	String	Filter by specific route short-name (e.g. `5`, `4`)
`lat`, `lon`	Float	Center coordinates for geographic searches. Requires `radius`.
`radius`	Float	Radius in meters for geo search (max allowed is determined by your plan).

Sample Response

{
  "count": 1,
  "timestamp": 1786523924000,
  "plan": "Developer",
  "vehicles": [
    {
      "id": "4120",
      "carrier": "ee_harjumaa_tlt",
      "carrier_name": "Tallinn Urban Transit",
      "company": "TLT (Tallinna Linnatranspordi AS)",
      "country": "EE",
      "region": "Tallinn",
      "route": "3",
      "destination": "Kadriorg",
      "type": "TRAM",
      "lat": 59.4372,
      "lon": 24.7453,
      "speed": 22,
      "bearing": 90,
      "model": "Škoda 15T ForCity",
      "updated_at": 1786523912000,
      "style": { "color": "#f59e0b", "label": "Tram" }
    }
  ]
}

Fetch Single Vehicle

Retrieve current information for a single specific vehicle by its unique ingestion ID.

GET /api/v1/vehicles/:id

GTFS-RT Protobuf Feed

Serves the entire active transport system as standard GTFS-Realtime vehicle positions in protobuf format. Easily integrated into systems like OpenTripPlanner, Valhalla, or QGIS.

GET /api/v1/gtfs-rt.pb

Supports filter query parameters: carrier, type, country.

GTFS-RT JSON Feed

A JSON-serialized version of the GTFS-RT feed, convenient for diagnostics or simple integrations.

GET /api/v1/gtfs-rt.json

Get API Stats

Returns general state statistics for all active vehicles, types, and transit systems.

GET /api/v1/stats

Sample Response

{
  "total_vehicles": 244,
  "active_carriers": 1,
  "timestamp": 1786523924000,
  "by_country": { "EE": 244 },
  "by_type": { "BUS": 180, "TRAM": 64 },
  "by_carrier": {
    "ee_harjumaa_tlt": {
      "count": 244,
      "name": "Tallinn Urban Transit",
      "company": "TLT (Tallinna Linnatranspordi AS)",
      "country": "EE"
    }
  }
}

WebSocket Streaming

Connect directly to receive active updates. Best for live-mapping frontends.

const socket = io('ws://localhost:8080');

socket.on('connected', (data) => {
  console.log('Connected! Active counts:', data.active_carriers);
  
  // Subscribe to TLT and HSL
  socket.emit('subscribe', ['ee_harjumaa_tlt', 'fi_uusimaa_hsl']);
});

socket.on('transit_update', (update) => {
  console.log('Update for', update.carrier, 'vehicles:', update.data);
});