The airport disruption API,
in fields you can read.

The airport disruption API is the planned machine-readable side of DwellTime.aero. It is designed to return one compact object for a given airport, terminal, and business type, carrying dwell-time pressure, demand pressure, and airport disruption risk, each with a time window, a confidence value, reason classes, and suggested actions. It is meant for engineers at travel platforms and airport service apps, dispatch and rostering systems, and airport-business operations teams who already run their own tooling around a terminal.

This page is a design preview. The API is not published, and the shapes below describe intent, not a contract you can build against today.

Design principles

Four rules shape the interface.

• A small number of stable, business-readable fields. A field name should make sense to the duty manager reading a dashboard built on it, not only to the engineer parsing it. Three scores, one window, one confidence value, two arrays.
• No aviation decoding required by the consumer. You never receive a raw observation or a coded forecast to interpret. You receive a level and the reasons behind it.
• Every signal carries confidence and reason classes. A level on its own is not enough to build a good interface. Your users should be able to see why a signal moved and how sure the model is.
• Scores are advisory. They are designed to inform a person who decides, not to fire an automated action. Treat a level as an input to a rota, a dispatch queue, or a notification, and keep a human in the loop.

On sources, as plain background: the signal layer is designed to combine categories of public aviation operational data, including flight schedule and status feeds, delay and cancellation reporting, and aviation weather observations and forecasts. None of that is passed through to you. The API is designed to return the business reading, not the source records.

The signal object

The object below is the canonical shape under design. It is the same payload used across this site, so an example seen on the product page matches what the API is planned to return.

{
  "airport": "EGLL",
  "terminal": "T2",
  "business_type": "airport_cafe",
  "dwell_time_pressure": "HIGH",
  "demand_pressure": "HIGH",
  "airport_disruption_risk": "MEDIUM",
  "confidence": 0.72,
  "window": "next_1_to_3_hours",
  "suggested_actions": [
    "increase_staffing",
    "increase_grab_and_go_stock",
    "prepare_hot_drinks_capacity"
  ],
  "reason_classes": [
    "weather_disruption_risk",
    "delay_pressure_rising",
    "passenger_waiting_time_likely_to_increase"
  ]
}

Enumerations

Risk levels apply to all three scores.

Windows describe the period a reading applies to.

Reason classes explain the movement. These are examples.

The reason class list is expected to grow. Treat it as an open set. Store unknown values, display them readably, and never fail a request because a class is unrecognized.

Planned endpoints

The routes below are illustrative. They show the intended shape of the interface and are not a published contract. Paths are shown without a host, because there is no live service to point at.

One illustrative exchange, trimmed for readability.

GET /signals/EGLL?terminal=T2&business_type=airport_cafe
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "airport": "EGLL",
  "terminal": "T2",
  "business_type": "airport_cafe",
  "dwell_time_pressure": "HIGH",
  "demand_pressure": "HIGH",
  "airport_disruption_risk": "MEDIUM",
  "confidence": 0.72,
  "window": "next_1_to_3_hours"
}

Event stream and webhooks

Polling is fine for a dashboard. For anything that pages a person, a push integration is the better fit. A webhook and a WebSocket event stream are both planned for the MVP, alongside the dashboard, email, and Slack delivery described on integrations.

The design intent is that a webhook fires when a score crosses a level for a watched airport and business type, not on every recalculation. Each delivery would carry an event identifier so you can discard repeats, because at-least-once delivery is the assumption. Failed deliveries would be retried with backoff for a bounded period, and your endpoint should answer quickly and do its work afterwards.

{
  "event_id": "evt_illustrative_0001",
  "event_type": "signal_level_changed",
  "airport": "EGLL",
  "terminal": "T2",
  "business_type": "airport_cafe",
  "previous": { "demand_pressure": "MEDIUM" },
  "current": { "demand_pressure": "HIGH" },
  "window": "next_1_to_3_hours",
  "confidence": 0.72,
  "reason_classes": ["delay_pressure_rising"]
}

Integration patterns

Rostering and staffing tools

Map demand_pressure and window onto the shift you are about to publish, and surface suggested_actions as a prompt rather than an edit. A HIGH reading three hours out is a reason to ask a manager whether to add cover, not a reason to change a rota automatically. See cafes and retail for how this reads on the floor.

Dispatch and curbside systems

Use airport_disruption_risk and dwell_time_pressure together to anticipate curbside demand shifting later than the schedule suggests. arrival_compression is the class to watch, because it points at pickups bunching rather than growing. See ground transport.

Customer-facing apps

Show the level and the reason in plain language, and show the confidence honestly. Passengers and guests read a hedge better than a wrong certainty, and hotels and lounges face the same problem at the front desk. See platforms for the wider integration picture.

Versioning and stability

Field names on this page may change before the pilot. The three score fields, the level enum, and the window enum are the parts we expect to hold. Reason classes, action codes, and the exact endpoint paths are the parts most likely to move.

Once the API is published, the intent is a versioned path, additive changes within a version, and advance notice with a migration window for anything breaking. Until then, treat this page as a design preview and build against it at your own pace.

What is not planned for the MVP

• No raw aviation weather passthrough. The product is a business signal layer, not a weather feed.
• No per-passenger data. Signals describe conditions and pressure, never individuals.
• No camera, sensor, or in-terminal hardware ingestion.
• No automated actions taken on your behalf. The API informs your systems. Your systems and your people decide.

If you want to shape the fields before they settle, the pilot is where that happens. If you are choosing between the API and a lighter path such as the dashboard or an alert channel, integrations compares them.