{"openapi": "3.1.0", "info": {"title": "Bilo transport data API", "version": "0.1.0", "description": "Reads collected Romanian rail data. Amounts are integer bani, RON. Exact collected quotes take priority. Derived, expired or uncertain fares carry is_estimate=true and display_label=Estimat. Annual calendar predictions do not confirm daily operation. City mapping coverage is explicit."}, "servers": [{"url": "/"}], "paths": {"/health": {"get": {"operationId": "health", "summary": "Service health; no source requests on reads", "parameters": [], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/locations": {"get": {"operationId": "suggestLocations", "summary": "Autocomplete cities and canonical passenger stations", "parameters": [{"name": "q", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "description": "", "schema": {"type": "integer"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/locations/{location_id}": {"get": {"operationId": "getLocation", "summary": "Get a canonical city or station", "parameters": [{"name": "location_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/cities": {"get": {"operationId": "listCities", "summary": "Official SIRUTA city identities and mapped passenger stations", "parameters": [{"name": "q", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/cities/{city_id}/stations": {"get": {"operationId": "getCityStations", "summary": "Passenger stations belonging to a city", "parameters": [{"name": "city_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/stations": {"get": {"operationId": "listStations", "summary": "Source station references or canonical stations for a city", "parameters": [{"name": "city", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/operators": {"get": {"operationId": "listOperators", "summary": "Collected operators and external booking links", "parameters": [], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/internal/overview": {"get": {"operationId": "getInternalOverview", "summary": "Local-only entire annual catalogue, collected observations, fares and schematic geography; no source requests", "parameters": [], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/search": {"get": {"operationId": "searchRoutes", "summary": "Expand city queries to station pairs; annual candidates with collected fares preferred", "parameters": [{"name": "origin", "in": "query", "required": true, "description": "City/station ID, city name or operator station name; accents are optional.", "schema": {"type": "string"}}, {"name": "destination", "in": "query", "required": true, "description": "City/station ID or name.", "schema": {"type": "string"}}, {"name": "date", "in": "query", "required": true, "description": "Travel date, YYYY-MM-DD in Europe/Bucharest.", "schema": {"type": "string"}}, {"name": "operator", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/journeys": {"get": {"operationId": "getCollectedJourneys", "summary": "Stored date-specific operator searches; no source requests on reads", "parameters": [{"name": "origin", "in": "query", "required": true, "description": "City/station ID, city name or operator station name; accents are optional.", "schema": {"type": "string"}}, {"name": "destination", "in": "query", "required": true, "description": "City/station ID or name.", "schema": {"type": "string"}}, {"name": "date", "in": "query", "required": true, "description": "Travel date, YYYY-MM-DD in Europe/Bucharest.", "schema": {"type": "string"}}, {"name": "operator", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/fares": {"get": {"operationId": "getFares", "summary": "Fares and route context, including explicit Estimat labels", "parameters": [{"name": "origin", "in": "query", "required": true, "description": "City/station ID, city name or operator station name; accents are optional.", "schema": {"type": "string"}}, {"name": "destination", "in": "query", "required": true, "description": "City/station ID or name.", "schema": {"type": "string"}}, {"name": "date", "in": "query", "required": true, "description": "Travel date, YYYY-MM-DD in Europe/Bucharest.", "schema": {"type": "string"}}, {"name": "operator", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/routes": {"get": {"operationId": "listRoutes", "summary": "Annual route definitions with ordered passenger/technical stops", "parameters": [{"name": "operator", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}, {"name": "train", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "description": "", "schema": {"type": "integer"}}, {"name": "offset", "in": "query", "required": false, "description": "", "schema": {"type": "integer"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/routes/{service_id}": {"get": {"operationId": "getRoute", "summary": "Full annual train route", "parameters": [{"name": "service_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/tariffs": {"get": {"operationId": "getTariffs", "summary": "Published adult tariff tables and source publications", "parameters": [{"name": "operator", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/train-details": {"get": {"operationId": "getTrainDetails", "summary": "Current official passenger-stop evidence", "parameters": [{"name": "operator", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}, {"name": "train", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}, {"name": "date", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/publications": {"get": {"operationId": "getPublications", "summary": "Collected current timetable grids and notices", "parameters": [{"name": "operator", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/booking-directories": {"get": {"operationId": "getBookingDirectories", "summary": "Current public operator station/train directories", "parameters": [{"name": "operator", "in": "query", "required": false, "description": "", "schema": {"type": "string"}}], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/references": {"get": {"operationId": "getReferences", "summary": "Annual source metadata, checksums and licences", "parameters": [], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/coverage": {"get": {"operationId": "getCoverage", "summary": "Route, fare and city-mapping coverage and explicit gaps", "parameters": [], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}, "/v1/status": {"get": {"operationId": "getCollectionStatus", "summary": "Last collection attempts and failures", "parameters": [], "responses": {"200": {"description": "Stored JSON result", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid parameters"}, "404": {"description": "Unknown ID"}, "409": {"description": "Ambiguous location; response includes choices"}}}}}, "components": {"schemas": {"Fare": {"type": "object", "required": ["amount_bani", "currency", "is_estimate", "display_label"], "properties": {"amount_bani": {"type": "integer", "minimum": 0, "description": "Exact stored amount in bani; 4150 = 41.50 RON."}, "currency": {"type": "string", "const": "RON"}, "class": {"type": ["string", "null"]}, "passenger": {"type": "string"}, "kind": {"type": "string"}, "accommodation": {"anyOf": [{"$ref": "#/components/schemas/Accommodation"}, {"type": "null"}]}, "is_estimate": {"type": "boolean"}, "display_label": {"enum": ["Estimat", null]}, "reference_travel_date": {"type": "string", "format": "date", "description": "Original travel date of an observed reference total; never a quote for the requested date."}, "requested_travel_date": {"type": "string", "format": "date"}, "estimate_reason": {"type": "string"}, "stale": {"type": "boolean"}, "collected_at": {"type": "string", "format": "date-time"}, "expires_at": {"type": "string", "format": "date-time"}, "source_url": {"type": "string"}}}, "Accommodation": {"type": "object", "required": ["code", "type", "label", "class"], "properties": {"code": {"type": "string", "examples": ["seat_2", "couchette_4", "sleeper_single"]}, "type": {"enum": ["seat", "couchette", "sleeper", "other"]}, "class": {"type": ["string", "null"], "description": "Seat class only; bed products are distinct and use null."}, "label": {"type": "string"}, "berths": {"type": "integer", "minimum": 1}, "source_label": {"type": "string"}}}, "City": {"type": "object", "required": ["id", "name", "siruta", "station_ids"], "properties": {"id": {"type": "string", "example": "city:ro:siruta:179132"}, "name": {"type": "string"}, "siruta": {"type": "string"}, "county": {"type": ["string", "null"]}, "station_ids": {"type": "array", "items": {"type": "string"}}}}, "Station": {"type": "object", "required": ["id", "name", "operator_refs", "is_passenger_station"], "properties": {"id": {"type": "string", "example": "station:ro:annual:10017"}, "name": {"type": "string"}, "city_id": {"type": ["string", "null"]}, "is_passenger_station": {"type": "boolean"}, "aliases": {"type": "array", "items": {"type": "string"}}, "operator_refs": {"type": "array", "items": {"type": "object"}}}}}}}