Get Pilot Reports (PIREPs)
aviation_get_pirepsRead-onlyIdempotent
Get recent Pilot Reports (PIREPs) near an airport or within a bounding box. Returns decoded turbulence, icing, and cloud reports with altitude, aircraft type, intensity, and the raw PIREP string. Requires either station_id (ICAO center point for radial search, e.g., KSEA) or bbox (area search) — not both. distance_nm belongs to the station_id search only, and altitude_min_ft must not exceed altitude_max_ft. min_intensity restricts the result to reports carrying a turbulence or icing layer at that intensity or above. limit bounds how many reports come back without changing what is searched, keeping the most recent. Coverage is US-centric; PIREPs are sparse and absence of reports does not imply smooth conditions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bbox | No | Geographic bounding box for area PIREP search. | |
| hours | No | How many hours of history to return. Default 3. | |
| limit | No | Maximum reports to return, applied last — after every filter and after ordering by observation time descending, so a limited result is the most recent reports rather than an arbitrary slice. It bounds the response without changing what is searched, which every other parameter does. Distinct from the 400-row upstream cap: a limited result examined every report it counted and withheld some, while a capped one never drew the rest. Selection is by recency alone, so pair it with min_intensity to bound a result by severity. Omit to return every match. Optional. | |
| station_id | No | ICAO station ID as center point for radial search (e.g., KSEA). Use with distance_nm. | |
| distance_nm | No | Search radius in nautical miles around station_id, defaulting to 100 when omitted. Belongs to the station_id search only — supplying it alongside bbox is rejected. | |
| min_intensity | No | Return only reports carrying at least one turbulence or icing layer at this intensity or above. The filter selects reports, not layers — a matching report still carries its lighter layers, so a result may include NEG, TRC, or LGT entries alongside the layer that matched. Optional. | |
| altitude_max_ft | No | Filter by maximum altitude in feet MSL (e.g., 35000 for FL350). Reports with an unknown altitude (altitude_ft null) cannot be shown to satisfy a bound and are dropped whenever either bound is set. Optional. | |
| altitude_min_ft | No | Filter by minimum altitude in feet MSL (e.g., 18000 for FL180). Reports with an unknown altitude (altitude_ft null) cannot be shown to satisfy a bound and are dropped whenever either bound is set. Optional. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The upstream row maximum that was applied to the page. Present only on a truncated result. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Reports in this result, counted after any altitude filter and after any limit. | |
| notice | No | Guidance for whichever disclosures fired: the levers that narrow the query before the cap applies, and what a requested limit withheld. Both can fire on one result, and the text keeps them apart. | |
| pireps | No | Pilot reports matching the search criteria, ordered by observation time descending. | |
| limited | No | True when the requested limit withheld reports that matched — the caller asked to see fewer of them. False affirms the limit did not bite, so every matching report is here. Present only when the call supplied a limit. It never states anything about the upstream cap: a limited result examined every report it counted, while a truncated one never drew the rest. | |
| matched | No | Reports that matched this query before the limit selected from them. Present only on a limited result. Where the result is also truncated this counts the capped page and not the search area — the reports the cap dropped were never examined, so no count can include them. | |
| truncated | No | True when the upstream page hit the AWC row cap, so reports inside the search area and time window are missing from this result. False affirms the whole window was searched, which a count alone cannot establish. | |
| upstreamRows | No | Reports AWC returned before the altitude filter ran. Present only on a truncated result the filter then narrowed, where the remaining count sits below the cap and so cannot reveal the truncation on its own. |