{
  "openapi": "3.1.0",
  "info": {
    "title": "TrainsRadar API",
    "version": "1.0.0",
    "summary": "Live trains and station departures, limited to data whose licence allows commercial redistribution.",
    "description": "Read-only JSON API. Every request needs a key in the `X-API-Key` header. The free Developer plan has a low daily quota (1,000 requests a day unless agreed otherwise) and is meant for non-bulk use. Only countries whose data licence allows commercial use and redistribution are served; each row carries the `license` that binds it, and each response lists the attributions you must show. Errors are `{error, code}` (plus `requestId` on server errors).",
    "contact": {
      "name": "TrainsRadar",
      "url": "https://trainsradar.com/api-docs#api-v1"
    },
    "termsOfService": "https://trainsradar.com/legal/terms"
  },
  "servers": [
    {
      "url": "https://trainsradar.com"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "tags": [
    {
      "name": "Trains",
      "description": "Trains running now"
    },
    {
      "name": "Stations",
      "description": "Live departure boards"
    },
    {
      "name": "Meta",
      "description": "Countries and licences"
    }
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "tags": [
          "Meta"
        ],
        "operationId": "getIndex",
        "summary": "Countries served and their licences",
        "responses": {
          "200": {
            "description": "API index",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "apiVersion",
                    "countries",
                    "licenses"
                  ],
                  "properties": {
                    "apiVersion": {
                      "type": "string",
                      "examples": [
                        "1.0.0"
                      ]
                    },
                    "openapi": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "string"
                    },
                    "countries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CountryCode"
                      }
                    },
                    "licenses": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/License"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/QuotaExceeded"
          }
        }
      }
    },
    "/api/v1/trains": {
      "get": {
        "tags": [
          "Trains"
        ],
        "operationId": "listTrains",
        "summary": "Trains running now",
        "description": "Trains with a live or estimated position in the countries the API serves (all of them, or one with `country`). Positions refresh about every 20 s.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "ISO 3166-1 alpha-2 code (case-insensitive) or ALL. A country outside the API is a 403.",
            "schema": {
              "type": "string",
              "default": "ALL",
              "examples": [
                "FI"
              ]
            }
          },
          {
            "name": "bounds",
            "in": "query",
            "description": "Only trains inside north,south,east,west (decimal degrees).",
            "schema": {
              "type": "string",
              "examples": [
                "60.4,60.0,25.2,24.6"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000,
              "default": 5000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trains",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "apiVersion",
                    "generatedAt",
                    "count",
                    "trains",
                    "licenses"
                  ],
                  "properties": {
                    "apiVersion": {
                      "type": "string"
                    },
                    "generatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "trains": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Train"
                      }
                    },
                    "licenses": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/License"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/CountryNotAvailable"
          },
          "429": {
            "$ref": "#/components/responses/QuotaExceeded"
          }
        }
      }
    },
    "/api/v1/trains/{id}": {
      "get": {
        "tags": [
          "Trains"
        ],
        "operationId": "getTrain",
        "summary": "One running train and its last positions",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Train id as returned by /api/v1/trains (e.g. fi-IC27).",
            "schema": {
              "type": "string",
              "maxLength": 128
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The train",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "apiVersion",
                    "train",
                    "history",
                    "licenses"
                  ],
                  "properties": {
                    "apiVersion": {
                      "type": "string"
                    },
                    "generatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "train": {
                      "$ref": "#/components/schemas/Train"
                    },
                    "history": {
                      "description": "Up to 10 positions of the last two hours, newest first.",
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "lat": {
                            "type": "number"
                          },
                          "lng": {
                            "type": "number"
                          },
                          "recordedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "licenses": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/License"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/QuotaExceeded"
          }
        }
      }
    },
    "/api/v1/stations/{id}/departures": {
      "get": {
        "tags": [
          "Stations"
        ],
        "operationId": "getDepartures",
        "summary": "Live departures of a station",
        "description": "Timetabled departures of the next `window` minutes (and the last 10), matched to the live trains: expected time, delay, platform when known.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Station id within its country.",
            "schema": {
              "type": "string",
              "maxLength": 128
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "ISO country code: station ids are only unique within a country.",
            "schema": {
              "type": "string",
              "examples": [
                "FI"
              ]
            }
          },
          {
            "name": "window",
            "in": "query",
            "description": "Minutes ahead.",
            "schema": {
              "type": "integer",
              "minimum": 15,
              "maximum": 240,
              "default": 90
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Departures",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "apiVersion",
                    "station",
                    "country",
                    "departures",
                    "licenses"
                  ],
                  "properties": {
                    "apiVersion": {
                      "type": "string"
                    },
                    "generatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "station": {
                      "type": "string"
                    },
                    "country": {
                      "$ref": "#/components/schemas/CountryCode"
                    },
                    "tz": {
                      "type": "string",
                      "description": "IANA zone the times are in.",
                      "examples": [
                        "Europe/Helsinki"
                      ]
                    },
                    "departures": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Departure"
                      }
                    },
                    "nextDeparture": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Epoch seconds of the first departure after the window, when the window has none ahead."
                    },
                    "licenses": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/License"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/CountryNotAvailable"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/QuotaExceeded"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "description": "Requests allowed per UTC day.",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Requests left today.",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Reset": {
        "description": "Seconds until the quota resets (00:00 UTC).",
        "schema": {
          "type": "integer"
        }
      }
    },
    "schemas": {
      "CountryCode": {
        "type": "string",
        "pattern": "^[A-Z]{2}$"
      },
      "License": {
        "type": "object",
        "required": [
          "country",
          "license",
          "attribution"
        ],
        "properties": {
          "country": {
            "$ref": "#/components/schemas/CountryCode"
          },
          "license": {
            "type": "string",
            "examples": [
              "CC BY 4.0"
            ]
          },
          "licenseUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "attribution": {
            "type": "string",
            "description": "Text the licence asks you to show next to the data."
          }
        }
      },
      "Train": {
        "type": "object",
        "required": [
          "id",
          "lat",
          "lng",
          "countryCode",
          "license"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "line": {
            "type": [
              "string",
              "null"
            ]
          },
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "GTFS-RT VehicleStopStatus when the feed gives it."
          },
          "nextStopId": {
            "type": [
              "string",
              "null"
            ]
          },
          "nextStopName": {
            "type": [
              "string",
              "null"
            ]
          },
          "delay": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Seconds; null when the feed gives none."
          },
          "type": {
            "type": [
              "string",
              "null"
            ]
          },
          "operator": {
            "type": [
              "string",
              "null"
            ]
          },
          "speedKmh": {
            "type": [
              "number",
              "null"
            ]
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "isInterpolated": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "True when the position is estimated from the timetable rather than reported by the train."
          },
          "countryCode": {
            "$ref": "#/components/schemas/CountryCode"
          },
          "license": {
            "type": "string"
          }
        }
      },
      "Departure": {
        "type": "object",
        "required": [
          "scheduledTime",
          "expectedTime",
          "destination",
          "state",
          "license"
        ],
        "properties": {
          "scheduledTime": {
            "type": "string",
            "description": "HH:MM, station time."
          },
          "expectedTime": {
            "type": "string"
          },
          "minutesToExpected": {
            "type": "integer"
          },
          "line": {
            "type": [
              "string",
              "null"
            ]
          },
          "destination": {
            "type": "string"
          },
          "operator": {
            "type": [
              "string",
              "null"
            ]
          },
          "delaySeconds": {
            "type": [
              "integer",
              "null"
            ]
          },
          "platform": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "scheduled",
              "en_route",
              "approaching",
              "at_station"
            ]
          },
          "trainId": {
            "type": [
              "string",
              "null"
            ]
          },
          "distanceKm": {
            "type": [
              "number",
              "null"
            ]
          },
          "number": {
            "type": [
              "string",
              "null"
            ]
          },
          "via": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "lat": {
            "type": [
              "number",
              "null"
            ]
          },
          "lng": {
            "type": [
              "number",
              "null"
            ]
          },
          "nextStop": {
            "type": [
              "string",
              "null"
            ]
          },
          "license": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "code"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "examples": [
              "invalid_param",
              "country_required",
              "invalid_country",
              "api_key_required",
              "invalid_api_key",
              "quota_exceeded",
              "country_not_available",
              "not_found",
              "internal_error"
            ]
          },
          "param": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          },
          "available": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CountryCode"
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid parameter",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid X-API-Key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "CountryNotAvailable": {
        "description": "The country's data licence does not allow commercial redistribution",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Not found (or not served by the API)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "QuotaExceeded": {
        "description": "Daily quota used up; Retry-After says when it resets (00:00 UTC)",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
