# BTS Flight On-Time Performance — US Airline Delays (`compute-edge/bts-flight-performance-scraper`) Actor Extract BTS monthly carrier on-time flight performance. 600K+ records/month with delays, cancellations, diversions, distances, and delay attribution. For travel analytics, route planning, delay-prediction ML, trip insurance pricing, and frequent-flyer apps. - **URL**: https://apify.com/compute-edge/bts-flight-performance-scraper.md - **Developed by:** [Compute Edge](https://apify.com/compute-edge) (community) - **Categories:** Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## BTS Flight On-Time Performance Scraper ### Overview This Actor downloads and parses the **Bureau of Transportation Statistics (BTS) On-Time Reporting Carrier** flight performance dataset — the official US government source for airline delay, cancellation, and performance data. Access monthly flight data for all US domestic carriers with powerful filtering options. **Key Features:** - **Free, no authentication required** — Download directly from official BTS servers - **Monthly datasets** — Full coverage from 1987 to present - **600K+ flights per month** — Complete US domestic flight records - **Rich filtering** — By airline, airport, state, route, delay, cancellation status - **Computed fields** — Delay categories, cancellation reasons, route keys for analysis - **Auto-updated** — BTS publishes new data monthly **Data fields:** Flight date, airline, flight number, tail number, origin/destination airports and cities, departure/arrival times and delays, cancellation/diversion status, distance, computed delay reasons (carrier, weather, NAS, security, late aircraft), and more. ### Use Cases - **Airline Performance Analysis** — Benchmark carriers by on-time performance, delay patterns, cancellation rates - **Route Planning & Optimization** — Identify problematic routes, seasonal delay trends - **Travel Insurance Pricing** — Historical delay data for risk modeling - **ML/AI Training Datasets** — Clean, normalized flight data for delay prediction models - **Frequent Flyer Programs** — Analyze airline reliability for loyalty decisions - **Airport Operations** — Understand origin/destination impact on delays - **Research & Economics** — Academic studies on transportation, supply chain disruption ### Input Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `year` | Integer | 2024 | Year for data (2010–2025) | | `month` | Integer | 12 | Month (1–12) | | `originAirport` | String | (all) | 3-letter origin airport code (e.g., `JFK`, `LAX`, `ORD`) | | `destAirport` | String | (all) | 3-letter destination airport code (e.g., `MIA`, `SFO`) | | `carrier` | String | (all) | Airline code (e.g., `AA`, `DL`, `UA`, `WN`, `B6`, `AS`) | | `cancelledOnly` | Boolean | false | Only return cancelled flights | | `divertedOnly` | Boolean | false | Only return diverted flights | | `delayedOnly` | Boolean | false | Only return flights with ≥15 min departure delay | | `originState` | String | (all) | 2-letter state code for origin (e.g., `CA`, `NY`, `TX`) | | `destState` | String | (all) | 2-letter state code for destination (e.g., `FL`, `HI`) | | `maxResults` | Integer | 5000 | Max records to return (0 = unlimited; monthly datasets contain 600K+ rows) | ### Output Fields Each record includes: **Flight Identifiers:** - `flightDate`, `year`, `month`, `dayOfMonth`, `dayOfWeek` - `carrier` (airline code), `flightNumber`, `tailNumber` **Route Information:** - `origin`, `originCity`, `originState`, `originStateName` - `dest`, `destCity`, `destState`, `destStateName` - `routeKey` (computed: `origin-dest`, e.g., `JFK-LAX`) - `distance` (miles) **Departure:** - `crsDepTime` (scheduled), `depTime` (actual), `depDelay` (signed minutes) - `depDelayMinutes` (absolute minutes late; null if on-time or early) - `depDel15` (boolean: delayed ≥15 minutes) - `taxiOut`, `wheelsOff` **Arrival:** - `crsArrTime` (scheduled), `arrTime` (actual), `arrDelay` (signed minutes) - `arrDelayMinutes`, `arrDel15` (boolean: delayed ≥15 minutes) - `wheelsOn`, `taxiIn` **Elapsed Time:** - `crsElapsedTime`, `actualElapsedTime`, `airTime` (in minutes) **Cancellation & Diversions:** - `cancelled` (boolean) - `cancellationCode` (A=Carrier, B=Weather, C=NAS, D=Security) - `cancellationReason` (mapped: "Carrier", "Weather", "NAS", "Security") - `diverted` (boolean) **Delay Breakdown (sum to total departure delay):** - `carrierDelay` (minutes — airline operational issue) - `weatherDelay` (minutes — weather at origin/destination) - `nasDelay` (minutes — NAS congestion) - `securityDelay` (minutes — security issue) - `lateAircraftDelay` (minutes — previous flight delay) **Computed Fields:** - `delayCategory` (one of: `on-time`, `delayed-minor` [15–60 min], `delayed-major` [>60 min], `cancelled`, `diverted`) ### Tutorial: Analyze JFK→LAX Delays 1. **Open the Actor Input Form** in Apify Console 2. **Configure inputs:** - `year`: 2024 - `month`: 12 - `originAirport`: JFK - `destAirport`: LAX - `maxResults`: 500 3. **Click Run** 4. **Wait for completion** (30–90 seconds depending on filters; larger datasets take longer) 5. **View Results:** - Open the **Dataset** tab - Analyze `depDelayMinutes`, `arrDelayMinutes`, `delayCategory` - Sort by delay to identify worst-performing flights - Filter by `carrier` to compare airlines on this route **Example insights:** - "JFK→LAX has avg departure delay of 12 minutes in December" - "Southwest (WN) had 3 cancellations, United (UA) had 0" - "Afternoon flights (14:00–18:00) show 18% more delays than morning" ### Tutorial: Find Airlines with Most Cancellations 1. **Inputs:** - `year`: 2024 - `month`: 12 - `cancelledOnly`: true - `maxResults`: 0 (unlimited) 2. **Run** → captures all cancellations for December 2024 3. **Export as CSV/JSON** 4. **Analyze in spreadsheet or Python:** ```python df = read_csv('dataset.csv') cancellations_by_carrier = df.groupby('carrier').size().sort_values(ascending=False) print(cancellations_by_carrier) ```` ### Data Schema & Completeness **Source:** Official Bureau of Transportation Statistics (BTS), U.S. Department of Transportation **Coverage:** All US-based carriers operating domestic flights **Data freshness:** BTS publishes preliminary data within 1–2 days of month end; final data within 2–3 weeks. This Actor downloads the latest available dataset for the requested month/year. **Completeness:** Fields are populated per BTS schema. Delays and cancellation reasons may be null if the flight was: - Cancelled before departure (no delay values) - Diverted (alternate dataset) - Early arrival (negative `depDelay`) **Note on large datasets:** December and summer months (June–August) have 600K+ rows. Use filters (`originAirport`, `carrier`, `delayedOnly`, `maxResults`) to keep compute costs manageable. ### Common Filters & Examples | Use Case | Input Config | |----------|--------------| | All Southwest flights in April 2025 | `carrier: "WN"`, `year: 2025`, `month: 4` | | Cancelled flights in California | `originState: "CA"`, `cancelledOnly: true` | | JFK departures in Dec 2024, first 100 | `originAirport: "JFK"`, `maxResults: 100` | | Morning flights (05:00–12:00) | No built-in filter; post-process `crsDepTime` | | Major delays on top 10 routes | `delayedOnly: true`, `maxResults: 50000` → group by `routeKey` | ### Pricing - **Per-result:** $0.003/record - **Compute units:** 1 run ≈ 0.5–2 compute units depending on dataset size and filters - **Example:** 5,000 records = ~$0.015 + ~0.5 compute units (~$0.025) = ~$0.04 total - **Full monthly dataset** (600K rows, no filters) ≈ $1.80 results + ~$1–2 compute = $4–5 total **Cost optimization:** - Use `maxResults` to limit output - Filter by `carrier` or `originAirport` to reduce processing - Export monthly, not weekly ### Troubleshooting **Q: "Failed to download BTS data" error** - Check that `year` is 2010–2025 and `month` is 1–12 - Older data (pre-2010) is not available via this URL pattern - BTS may delay monthly publishing by 1–2 weeks; try the prior month **Q: Got 0 results with filters applied** - Your filter combination may have no matches (e.g., carrier "FX" doesn't exist) - Check airport codes are valid 3-letter IATA codes - State codes must be 2-letter (e.g., "CA" not "California") **Q: Dataset very large, run timed out** - Monthly datasets (600K+ rows) can take 2–5 minutes to parse - Use `maxResults` to cap output - Add `delayedOnly: true` or filter by `carrier`/`originAirport` **Q: Data doesn't match BTS website directly** - This Actor downloads the raw "Reporting Carrier" dataset from BTS - BTS website may show aggregated or summarized data; raw CSVs are authoritative - Dates are in ISO format (YYYY-MM-DD); BTS website may display differently ### Similar Actors - **[US Airport Operations Tracker](https://apify.com/store)** — Real-time airport delays and statistics (complement to historical BTS data) - **[Flight Price Tracker](https://apify.com/store)** — Current flight prices and availability - **[Airline News Monitor](https://apify.com/store)** — Track airline announcements and alerts ### Legal & Attribution **Open Data:** BTS flight data is public domain. No authentication or payment to BTS is required. **Proper Attribution:** When publishing analysis: - Cite "U.S. Department of Transportation, Bureau of Transportation Statistics" - Include: "Data source: BTS On-Time Reporting Carrier dataset" **Disclaimer:** This Actor provides data as-is. Apify and the creator are not liable for inaccuracies or delays in BTS data publishing. For regulatory/legal decisions, refer to official BTS sources directly. **Terms:** Use this Actor only for lawful purposes. Reselling BTS data without attribution violates open data principles. Proper attribution is requested but not legally required (BTS is public domain). ### Support - **Questions?** Check this README or contact support via Apify - **Data quality issues?** Report directly to [BTS](https://transtats.bts.gov/) — this Actor mirrors their official datasets - **Actor bugs?** File an issue or contact the developer *** **Last updated:** May 2025\ **Version:** 0.1 # Actor input Schema ## `year` (type: `integer`): Year for flight data (2010-2025). Default: 2024. ## `month` (type: `integer`): Month (1-12). Default: 12 (December). ## `originAirport` (type: `string`): Filter by origin airport code (3-letter, e.g. 'JFK', 'LAX', 'ORD'). Leave blank for all airports. ## `destAirport` (type: `string`): Filter by destination airport code (3-letter, e.g. 'MIA', 'SFO'). Leave blank for all airports. ## `carrier` (type: `string`): Filter by airline code (e.g. 'AA' American, 'DL' Delta, 'UA' United, 'WN' Southwest). Leave blank for all airlines. ## `cancelledOnly` (type: `boolean`): If enabled, only return cancelled flights. ## `divertedOnly` (type: `boolean`): If enabled, only return diverted flights. ## `delayedOnly` (type: `boolean`): If enabled, only return flights with departure delay >= 15 minutes. ## `originState` (type: `string`): Filter by origin state code (2-letter, e.g. 'CA', 'NY', 'TX'). Leave blank for all states. ## `destState` (type: `string`): Filter by destination state code (2-letter, e.g. 'FL', 'HI'). Leave blank for all states. ## `maxResults` (type: `integer`): Maximum number of flight records to return. Set to 0 for unlimited (dataset can have 600K+ rows per month). ## Actor input object example ```json { "year": 2024, "month": 12, "originAirport": "", "destAirport": "", "carrier": "", "cancelledOnly": false, "divertedOnly": false, "delayedOnly": false, "originState": "", "destState": "", "maxResults": 5000 } ``` # Actor output Schema ## `dataset` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("compute-edge/bts-flight-performance-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("compute-edge/bts-flight-performance-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call compute-edge/bts-flight-performance-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=compute-edge/bts-flight-performance-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "BTS Flight On-Time Performance — US Airline Delays", "description": "Extract BTS monthly carrier on-time flight performance. 600K+ records/month with delays, cancellations, diversions, distances, and delay attribution. For travel analytics, route planning, delay-prediction ML, trip insurance pricing, and frequent-flyer apps.", "version": "0.1", "x-build-id": "QLfuNxC8esZoYsmPy" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/compute-edge~bts-flight-performance-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-compute-edge-bts-flight-performance-scraper", "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/compute-edge~bts-flight-performance-scraper/runs": { "post": { "operationId": "runs-sync-compute-edge-bts-flight-performance-scraper", "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/compute-edge~bts-flight-performance-scraper/run-sync": { "post": { "operationId": "run-sync-compute-edge-bts-flight-performance-scraper", "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": { "year": { "title": "Year", "minimum": 2010, "maximum": 2025, "type": "integer", "description": "Year for flight data (2010-2025). Default: 2024.", "default": 2024 }, "month": { "title": "Month", "minimum": 1, "maximum": 12, "type": "integer", "description": "Month (1-12). Default: 12 (December).", "default": 12 }, "originAirport": { "title": "Origin Airport", "type": "string", "description": "Filter by origin airport code (3-letter, e.g. 'JFK', 'LAX', 'ORD'). Leave blank for all airports.", "default": "" }, "destAirport": { "title": "Destination Airport", "type": "string", "description": "Filter by destination airport code (3-letter, e.g. 'MIA', 'SFO'). Leave blank for all airports.", "default": "" }, "carrier": { "title": "Carrier", "type": "string", "description": "Filter by airline code (e.g. 'AA' American, 'DL' Delta, 'UA' United, 'WN' Southwest). Leave blank for all airlines.", "default": "" }, "cancelledOnly": { "title": "Cancelled Flights Only", "type": "boolean", "description": "If enabled, only return cancelled flights.", "default": false }, "divertedOnly": { "title": "Diverted Flights Only", "type": "boolean", "description": "If enabled, only return diverted flights.", "default": false }, "delayedOnly": { "title": "Delayed Flights Only", "type": "boolean", "description": "If enabled, only return flights with departure delay >= 15 minutes.", "default": false }, "originState": { "title": "Origin State", "type": "string", "description": "Filter by origin state code (2-letter, e.g. 'CA', 'NY', 'TX'). Leave blank for all states.", "default": "" }, "destState": { "title": "Destination State", "type": "string", "description": "Filter by destination state code (2-letter, e.g. 'FL', 'HI'). Leave blank for all states.", "default": "" }, "maxResults": { "title": "Max Results", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of flight records to return. Set to 0 for unlimited (dataset can have 600K+ rows per month).", "default": 5000 } } }, "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 } } } } } } } } } } ```