FAA OE/AAA Obstruction Radius Watcher

Monitor public FAA OE/AAA obstruction cases and turn geofences, structure types, sponsors, and status-code watchlists into structured events for aviation consultants, tower developers, renewable-energy teams, construction planners, site-diligence workflows, and AI agents.

What This Actor Does

• Fetches public FAA OE/AAA obstruction cases from the official REST/XML service.
• Matches cases against up to 10 user geofences.
• Filters by FAA structure type, sponsor keyword, status code, date window, and temporary/clutter suppression.
• Normalizes matched cases into event records with FAA case URLs, coordinates, heights, dates, determination/status fields, match terms, and raw source payloads.
• Persists event fingerprints and case snapshots so repeat runs do not re-emit the same event.
• Supports pay-per-event charging with a safe no-op fallback for local or unpublished runs.

Inputs

• geofences: up to 10 circles with lat, lon, radiusKm, and optional label. Boundary matches are included.
• structureTypes: FAA structure type prefixes or full values, such as WINDMILL, TOWER, or TOWER$ANTENNA.
• sponsorKeywords: sponsor/company keywords matched with word boundaries.
• statusCodes: exact FAA status-code values, such as DET-DNE, DET-DNH, or DET-M&L.
• dateWindow: explicit { "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" } or { "lookbackDays": 10 }.
• includeTemporaryStructures: default false. When false, suppresses status codes ending -TMP plus CRANE and CONSTRUCTION structure prefixes.
• maxEvents: safety cap for one run.
• stateStoreName: named key-value store for dedupe and determination snapshots. Public example tasks can use __RUN_DEFAULT__.

Output

Each dataset item uses this event shape:

{
    "source_case_url": "https://oeaaa.faa.gov/oeaaa/services/case/2026-WTE-575-OE",
    "source_api_url": "https://oeaaa.faa.gov/oeaaa/services/caseList/date/OE?start=2026-06-25&end=2026-07-04",
    "event_type": "geofence_match",
    "entities": {
        "asn": "2026-WTE-575-OE",
        "status_code": "DET-DNH",
        "sponsor": "Flowing Well Wind, LLC",
        "structure_type": "WINDMILL",
        "nearest_city": "Revillo",
        "nearest_state": "SD",
        "matched_geofences": [{ "label": "Revillo SD wind project", "distance_km": 0 }]
    },
    "location": {
        "latitude": 45.06789167,
        "longitude": -96.50583889,
        "coordinates_basis": "parsed",
        "lat_long_accuracy": "4D"
    },
    "measurements": {
        "agl_structure_height_ft": 650,
        "agl_structure_height_determination_ft": 650
    },
    "match_terms": ["geofence:Revillo SD wind project", "structure_type:WINDMILL"],
    "case_baseline": "first_seen",
    "changed_fields": []
}

Event Pricing Plan

Pay-per-event pricing is configured on Apify.

• geofence_match: $0.05 primary event.
• new_obstruction_case: $0.03.
• determination_change: $0.04.

Use all-inclusive pay-per-event pricing. Do not enable pay-per-event plus usage unless the margin model changes.

Local Development

npm install
npm run build
npm test
npm run lint
npm run canary
apify run --purge

The local smoke input lives at storage/key_value_stores/default/INPUT.json.

Data Sources

• FAA OE/AAA portal: https://oeaaa.faa.gov/
• Case-list endpoint: https://oeaaa.faa.gov/oeaaa/services/caseList/date/OE
• Case-detail endpoint: https://oeaaa.faa.gov/oeaaa/services/case/<asn>
• FAA obstruction evaluation overview: https://www.faa.gov/air_traffic/obstruction_evaluation

Limitations

• This Actor reports public FAA source facts and watchlist matches. It does not determine whether a structure is safe, lawful, or acceptable for airspace purposes.
• FAA status codes are emitted as source codes. The Actor does not invent legal expansions when the source endpoint does not provide a legend.
• Temporary determinations and CRANE/CONSTRUCTION prefixes are suppressed by default to reduce noise; set includeTemporaryStructures to include them.
• lat_long_accuracy is passed through from FAA. Users should treat geofence matches according to the source coordinate accuracy.
• Cases without parsed coordinates cannot produce geofence_match, but can still produce non-geofence watchlist events.
• This Actor is not affiliated with, endorsed by, or sponsored by FAA, DOT, or the U.S. government.

Maintenance

Run the canary daily:

$npm run canary

Open a fix ticket if the endpoint returns HTML/404, recent windows are empty twice, required fields disappear, or case detail lookup no longer returns the requested ASN.

Kill / Scale Gate

After 60 days listed on Apify, continue only if the Actor reaches at least 5 paid-plan users or about $25 in charged events. Otherwise archive/freeze and move to the next finalist.