{ "openapi": "3.0.1", "info": { "title": "US Airline Fare & Route-Market Analytics (BTS DB1B)", "description": "Historical US airline fares and route economics by quarter, from the official BTS DB1B 10% ticket survey. Average and median fares, carrier market share and concentration (HHI), distance and estimated passengers by route, carrier or airport, with honest sample weighting. Not live booking prices.", "version": "1.0", "x-build-id": "bxC5g0a3zwZoEvCNo" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/malonestar~bts-db1b-fare-route-market-analytics/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-malonestar-bts-db1b-fare-route-market-analytics", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/malonestar~bts-db1b-fare-route-market-analytics/runs": { "post": { "operationId": "runs-sync-malonestar-bts-db1b-fare-route-market-analytics", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/malonestar~bts-db1b-fare-route-market-analytics/run-sync": { "post": { "operationId": "run-sync-malonestar-bts-db1b-fare-route-market-analytics", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "sinceQuarter": { "title": "First quarter (YYYY-Qn)", "pattern": "^$|^\\d{4}-[Qq]?[1-9]$", "type": "string", "description": "First quarter of BTS DB1B data to include, as YYYY-Qn (e.g. \"2025-Q1\") or YYYY-n (e.g. \"2025-1\"), n being 1-4. Leave blank to default to the quarter before the latest published quarter. The DB1B Origin & Destination Survey begins 1993-Q1 and is published with a ~1-2 quarter lag; the run discovers the latest available quarter live and reports it on every row. An unusable value (a month form, slash date, bare year, or quarter 5) FAILS the run loudly — it is never silently ignored." }, "untilQuarter": { "title": "Last quarter (YYYY-Qn)", "pattern": "^$|^\\d{4}-[Qq]?[1-9]$", "type": "string", "description": "Last quarter of BTS DB1B data to include, as YYYY-Qn or YYYY-n. Leave blank to default to the latest published quarter. A window spanning more than 4 quarters is rejected (each quarter is a ~100 MB, ~7-million-row BTS download). A quarter BTS has not yet published is reported as missing — with allowPartial false (the default) the run fails loudly rather than quietly narrowing your window." }, "origins": { "title": "Origin airports (optional filter)", "type": "array", "description": "Optional. IATA origin airport codes, e.g. [\"LAX\",\"JFK\"]. Leave empty for all origins. Markets are DIRECTIONAL in DB1B, so LAX-JFK and JFK-LAX are separate rows. An unfiltered, all-routes run over a full quarter aggregates tens of thousands of markets and is memory-heavy; a filter keeps it light.", "items": { "type": "string" } }, "dests": { "title": "Destination airports (optional filter)", "type": "array", "description": "Optional. IATA destination airport codes, e.g. [\"JFK\",\"ORD\"]. Leave empty for all destinations.", "items": { "type": "string" } }, "carriers": { "title": "Ticketing carriers (optional filter)", "type": "array", "description": "Optional. BTS ticketing-carrier codes to include, e.g. [\"WN\",\"AA\",\"DL\",\"UA\",\"B6\"]. Market share and fares are attributed to the TICKETING carrier (who sold the ticket); the operating carrier differs on ~27% of rows (codeshare/regional). Leave empty for all carriers (DB1B includes ~37 codes, incl. foreign carriers on US-endpoint itineraries and a \"--\" placeholder). A code matching no rows fails the run with the list of carriers actually present — never a silent empty dataset.", "items": { "type": "string" } }, "groupBy": { "title": "Group results by", "enum": [ "route", "carrier_route", "origin_airport", "market" ], "type": "string", "description": "How to roll markets up. \"route\" = one row per (directional origin-dest x quarter) across carriers; \"carrier_route\" = one row per (ticketing carrier x origin-dest x quarter); \"origin_airport\" = one row per (origin airport x quarter, all its outbound markets); \"market\" = one row per (origin city-market x dest city-market x quarter), which groups multi-airport metros (e.g. all NYC airports together). Carrier market-share/HHI fields are meaningful for route/origin_airport/market (which span carriers) and trivial for carrier_route. Omitted = \"route\"." }, "minPassengers": { "title": "Minimum sample passengers per group", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Suppress groups with fewer than this many SAMPLE passengers in a quarter (noise control — a market with 2 sampled passengers gives a meaningless average fare). Remember DB1B is a 10% sample, so 10 sample passengers ~ 100 estimated. Suppressed-group count is disclosed on every emitted row as groups_suppressed_below_min_passengers. Set 0 to keep everything. Omitted = 10." }, "maxResults": { "title": "Max results", "minimum": 1, "maximum": 20000, "type": "integer", "description": "Hard cap on emitted rows — each row is one billed result. Enforced by a single audited code path for every groupBy mode; when the cap bites, rows are dropped smallest-groups-first and every emitted row carries results_truncated=true. Omitted = 500." }, "allowPartial": { "title": "Allow partial quarter window", "type": "boolean", "description": "If a requested quarter cannot be retrieved (not yet published by BTS, or the download failed), the run FAILS loudly by default so a partial window is never mistaken for a complete one. Set true to proceed with the quarters that did arrive — every row then reports quarters_missing and data_complete=false.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }