{
  "openapi": "3.0.3",
  "info": {
    "title": "Traffic Archive History API",
    "version": "1.0.0",
    "description": "Regional recorded observations and bounded historical samples. Not complete global traffic. Timestamps in responses are Unix milliseconds (UTC). Public source licences remain applicable."
  },
  "servers": [
    {
      "url": "https://trafficarchive.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "rt_\u2026"
      }
    }
  },
  "paths": {
    "/api/v1/coverage": {
      "get": {
        "summary": "Inspect current coverage before subscribing",
        "responses": {
          "200": {
            "description": "Coverage, available dates and open-data licence links"
          }
        }
      }
    },
    "/api/v1/history": {
      "get": {
        "summary": "Query historical observations",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "required": false,
            "description": "recorded, flight-sample or ship-sample",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "description": "europe, america, asia or gulf; used for recorded",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "all, flight or ship",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "Inclusive ISO 8601 UTC timestamp",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "Inclusive ISO 8601 UTC timestamp, within 31 days of from",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 48 frames, default 24",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Offset returned as nextCursor from prior response",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "frames, dataset, nextCursor, remainingRequests and licences"
          },
          "400": {
            "description": "Invalid parameters"
          },
          "401": {
            "description": "Paid API key required"
          },
          "429": {
            "description": "Rate or monthly quota exceeded"
          },
          "503": {
            "description": "Provider or billing verification unavailable"
          }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "summary": "Read current billing-period usage without consuming history quota",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "used, limit, periodEnd"
          },
          "401": {
            "description": "Paid API key required"
          }
        }
      }
    }
  }
}