{
  "openapi": "3.1.0",
  "info": {
    "title": "FasTrak Trip Explorer Read-only API",
    "version": "0.1.0",
    "description": "Public built-in location references and import format documentation. Imported transactions, account details, and custom browser station legends are never returned. Locations are approximate; express lane station code coverage is partial."
  },
  "servers": [{ "url": "/" }],
  "paths": {
    "/api/stations": {
      "get": {
        "operationId": "getBuiltInStations",
        "summary": "Read built-in stations, facilities, and coverage limits",
        "description": "Includes reference points for all eight Bay Area toll bridges and a partial express lane station catalog. App bridge aliases are lookup labels, not verified official statement codes. Does not return custom legends or user transactions.",
        "responses": {
          "200": {
            "description": "Built-in catalog and coverage notes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["stations", "facilities", "coverage"],
                  "properties": {
                    "stations": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Station" }
                    },
                    "facilities": {
                      "type": "array",
                      "description": "Bay Area bridge and express lane facility references.",
                      "items": { "$ref": "#/components/schemas/TollFacility" }
                    },
                    "coverage": {
                      "type": "object",
                      "description": "Coverage scope, official sources, and mapping limitations.",
                      "properties": {
                        "bridges": { "type": "integer" },
                        "expressLaneCorridors": { "type": "integer" },
                        "verifiedStatementCodes": { "type": "integer" },
                        "completeOfficialCodeRegister": { "type": "boolean" },
                        "note": { "type": "string" }
                      },
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/import-schema": {
      "get": {
        "operationId": "getImportSchema",
        "summary": "Read the canonical transaction import structure",
        "description": "Returns a lightweight JSON Schema for canonical field names in transaction arrays or transactions envelopes. It is not a complete semantic validator or every accepted heading alias. Runtime parsing additionally checks dates, times, amounts, and row-specific endpoint requirements. This route only returns documentation and does not accept an upload.",
        "responses": {
          "200": {
            "description": "Lightweight canonical JSON structure and runtime validation notes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Station": {
        "type": "object",
        "required": ["code", "name", "direction", "lat", "lng"],
        "properties": {
          "code": { "type": "string" },
          "name": { "type": "string" },
          "direction": { "type": "string" },
          "lat": { "type": ["number", "null"], "minimum": -90, "maximum": 90 },
          "lng": {
            "type": ["number", "null"],
            "minimum": -180,
            "maximum": 180
          },
          "kind": { "type": "string", "enum": ["bridge", "express-lane"] },
          "road": { "type": "string" },
          "source": { "type": "string" },
          "coordinateSource": { "type": "string" },
          "coordinateNote": { "type": "string" },
          "aliases": { "type": "array", "items": { "type": "string" } },
          "codeType": {
            "type": "string",
            "enum": ["statement", "app-alias", "user"]
          },
          "legacy": { "type": "boolean" }
        }
      },
      "TollFacility": {
        "type": "object",
        "required": [
          "id",
          "name",
          "kind",
          "road",
          "source",
          "statementCodeCoverage"
        ],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "kind": { "type": "string", "enum": ["bridge", "express-lane"] },
          "road": { "type": "string" },
          "source": { "type": "string" },
          "statementCodeCoverage": {
            "type": "string",
            "enum": ["partial", "facility-aliases"]
          },
          "note": { "type": "string" }
        }
      }
    }
  }
}