Report Builder

Getting Started

The FlightAware Report Builder lets you query AeroAPI using a drag-and-drop pivot table interface. Instead of writing raw API calls, you pick fields, set filters, and the tool builds and executes the queries for you — including automatic pagination and date-range chunking.

Step 1 — Get an AeroAPI Key

1Go to flightaware.com/aeroapi/portal and sign up.

2Choose a tier — Personal ($0 free trial with limited calls), Standard, or Premium.

3Copy your API key from the portal dashboard.

Step 2 — Start the Proxy Server

Browsers can't call AeroAPI directly (CORS). Open a terminal and run the local proxy server:

cd /path/to/your/folder
python3 server.py

Then open http://localhost:8090 in your browser. The status bar should show PROXY ✓ in green.

Step 3 — Connect Your Profile

1Click 👤 Connect in the top-right header.

2Enter a profile name (e.g. "My AeroAPI Key") and paste your API key.

3Click 🔗 Connect & Save. The tool validates against /airports/KJFK.

4If valid, the status dot turns green and your profile name appears in the header.

You can save multiple profiles (e.g. personal vs. team keys) and switch between them. Profiles are stored in localStorage.

Step 4 — Build a Report

Choose a Data Source — The dropdown controls which AeroAPI endpoint is called and which fields appear in the sidebar:

• Flights by Ident — Flights for a tail number or flight ID (/flights/{ident}). With dates >10 days back, auto-routes to /history/flights/{ident}.
• Airport Flights — Arrivals/departures at an airport (/airports/{ident}/flights). With dates >10 days back, auto-routes to the history endpoint.
• Operator Flights — All flights for an airline (/operators/{ident}/flights). With dates >10 days back, auto-routes to the history endpoint. Great for large pulls like 1 year of AAL flights.
• Airport Info — Static airport data like elevation, timezone (/airports/{ident})
• Operator Info — Airline details like callsign, country (/operators/{ident})

When dates push beyond the 10-day recent-data limit, the tool automatically switches to the /history/ endpoint. A HISTORY API badge appears in the cost bar to confirm this. History endpoints cost $0.01/page.

The left sidebar automatically filters to show only fields available for the selected source.

Enter an Identifier — Depends on the source:

• Flights: tail number (N108US) or flight ident (SWA45)
• Airport: IATA code (DFW, JFK)
• Operator: ICAO operator code (AAL, UAL)

Set Date Range — Optional for flight sources (recent data if omitted, auto-routes to history if >10 days back). The tool automatically chunks requests into time windows and stitches results together. Recent endpoints use 7-day windows; history endpoints use 1-day (24hr) windows per AeroAPI constraints. A 30-day historical range = ~30 API calls (one per day).

Depth / Record Limit — Choose how many pages to fetch, or select "All records" to paginate until all data is retrieved. "All records" is the default and is needed for large pulls (e.g., 1 year of AAL flights). Cost is per page regardless of setting.

Drag Fields — Drag fields from the left sidebar into the four pivot zones:

• Filters — Narrow results client-side (e.g. only B738 aircraft, only flights to KJFK). A field can be in Filters AND in Rows/Columns simultaneously.
• Rows — Vertical grouping. Each unique combination becomes a row in the output.
• Columns — Horizontal cross-tab. Unique values become column headers.
• Values — Numeric fields to aggregate: SUM, AVG, COUNT, MIN, MAX.

Understanding Rows vs. Columns

Both Rows and Columns pull the same data from the API — the difference is how results display in the pivot table.

Example: You query historical flights for N108US over 30 days with these fields:

• Rows: Aircraft Type
• Columns: Origin ICAO
• Values: COUNT(Flight Ident)

This produces a matrix where each row is an aircraft type, each column is an origin airport, and each cell is the count of flights — like a cross-tab / pivot table.

If both Aircraft Type and Origin ICAO were in Rows instead, you'd get a flat grouped list with one row per unique combination, which is simpler but less visual.

Reordering & Moving Fields

You can drag chips between zones — e.g. move a field from Rows to Columns without removing it first. You can also drag chips within a zone to reorder them (row order affects grouping priority). The "✕ Clear All" button resets all zones.

Use the ▼ All / ▶ All buttons to expand or collapse all field groups, and the search bar to find fields quickly.

Cost Estimation

The action bar shows a real-time cost breakdown before you run:

• Calls — Number of API calls required for your date range. History endpoints use 1-day windows, so a 60-day range = 60 calls.
• Per-page cost — The AeroAPI price per page for the selected endpoint. History endpoints cost $0.010/page, recent endpoints $0.005/page.
• Min cost — The minimum cost assuming 1 page per call. Actual cost will be higher if there is more data (each page holds ~15 records and the tool fetches all pages automatically).

The breakdown reads left to right: [calls] × $price/pg = $min – $max

Test Limit

Use the Test limit input to cap the number of API calls for testing. For example, if your query would make 365 calls, set test limit to 5 to fetch just the first 5 days of data. Leave blank to fetch everything.

API Filters

When using Airport Flights or Operator Flights, an API FILTERS bar appears below the source selector. These filters are applied server-side by AeroAPI before data is returned, which reduces the number of pages fetched and lowers cost:

• Flight Type — Filter to Airline or General Aviation flights only. Available for Airport and Operator endpoints.
• Airline — Filter airport results to a specific airline (e.g. AAL for American, UAL for United). Available for Airport endpoints only.

Aborting a Report

While a report is running, the Run button becomes a red ⏹ Abort button showing live progress: call number, record count, and running cost (e.g. ⏹ 8/62 pg12 · 23,669 recs · $19.70). The cost bar also updates in real-time so you can watch the meter climb. Click Abort to stop — all data already fetched is kept and rendered as partial results.

Calculated Fields

The Calculated Fields group in the sidebar provides derived metrics computed automatically from OOOI times (Out, Off, On, In):

• Taxi Out — Minutes from gate departure to wheels-up (actual_off − actual_out)
• Taxi In — Minutes from wheels-down to gate arrival (actual_in − actual_on)
• Flight Time — Minutes airborne, wheels-up to wheels-down (actual_on − actual_off). Also available in decimal hours.
• Block Time — Total gate-to-gate time (actual_in − actual_out). Also available in decimal hours.

Drag these into Values with SUM to get total flight hours, AVG for average taxi times, etc. They work with all grouping and filtering — e.g. SUM of Flight Time (hrs) by Aircraft Type gives fleet utilization by type.

Date Grouping

When you drag a date/time field (like Actual Out or Scheduled In) into Rows or Columns, a bucket selector appears on the chip: Raw, Day, Week, Month, Qtr, Year.

• Raw — Full datetime (default, one row per flight)
• Day — Groups by date (2024-01-15)
• Week — ISO week (2024-W03)
• Month — Year-month (2024-01)
• Qtr — Quarter (2024 Q1)
• Year — Year only (2024)

Combined with calculated fields, this enables powerful analyses like: Actual Out bucketed by Month in Rows, Aircraft Type in Columns, SUM of Flight Time (hrs) in Values → monthly flight hours by fleet type.

Sorting & Column Filters

Sorting: Click any column header to sort ascending, click again for descending. Works in Pivot, Raw, and flat table views.

Column Filters (Excel-style): Each column header has a small ▼ filter icon. Click it to open a dropdown showing all unique values in that column with counts. Check/uncheck values to include or exclude them. Use "Select all" / "Deselect all" for quick toggling, and the search box to find specific values. Active filters show a yellow ▼ icon. Clear all column filters at once from the results info bar.

Column filters stack with the drag-and-drop zone filters — zone filters apply first (server-side logic), then column filters narrow the visible rows further.

Checking Usage & Billing

Click 💰 Usage in the header to view your current billing cycle's API usage. This calls GET /account/usage which is free (no charge). It shows a breakdown by endpoint with query counts and costs. Data updates every ~10 minutes. For the full dashboard, visit flightaware.com/commercial/aeroapi/billing/activity/recent.

Viewing Results

After running, results appear in the main area. Use the toolbar to switch between:

• Table — Flat or pivoted table depending on your zone configuration
• JSON — Raw API response data for debugging
• ⬇ CSV — Export the current data as a CSV file

Example Workflows

What aircraft types does SWA fly out of Dallas?

• Source: Airport Flights — Identifier: KDAL
• Rows: Operator (ICAO) — Filter: Operator = SWA
• Columns: Aircraft Type — Values: COUNT(Flight Ident)

N108US route history over 30 days:

• Source: Flights by Ident — Identifier: N108US — Date: 30-day range (auto-routes to history)
• Rows: Origin ICAO, Dest ICAO — Values: COUNT(Flight Ident), AVG(Departure Delay)

Daily departure count at JFK:

• Source: Airport Flights — Identifier: JFK — Date: 7-day range
• Rows: Scheduled Out (Gate) — Values: COUNT(Flight Ident)

Full year of AAL flights (large pull):

• Source: Operator Flights — Identifier: AAL — Date: Jan 1 to Dec 31 (auto-routes to history)
• Depth: "All records" — this will auto-chunk into ~365 daily API calls (history endpoints use 1-day windows) and paginate each fully
• Rows: Origin ICAO, Dest ICAO — Columns: Aircraft Type — Values: COUNT(Flight Ident)
• Use the Raw view + CSV export to get the complete dataset

AeroAPI Pricing Reference

• Flights by Ident: $0.005/page (recent) · $0.01/page (history)
• Airport Flights: $0.01/page
• Operator Flights: $0.01/page
• Airport Info: $0.005/query
• Operator Info: $0.005/query
• Account Usage: FREE

Troubleshooting

• Status dot stays red — Make sure python3 server.py is running and you opened http://localhost:8090 (not the file directly)
• "Invalid API key" — Double-check your key at flightaware.com/aeroapi/portal. Make sure you copied the full key with no extra spaces.
• No results — Try a known tail number like N108US or a major airport like KJFK. For historical, make sure the date range includes actual flights.
• Run button disabled — You need: (1) a connected profile, (2) an identifier entered, and (3) at least one field in Rows, Columns, or Values.