> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airrating.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Risk Score

> Calculate the delay risk score for a specific flight.

## Overview

The core endpoint. Returns a Risk Score (0–100) for a given route, airline, and date, along with historical statistics, weather data, risk drivers, and an optional news feed.

## Request

<ParamField query="origin" type="string" required>
  IATA code of the departure airport (e.g. `FCO`, `LHR`, `JFK`).
</ParamField>

<ParamField query="dest" type="string" required>
  IATA code of the arrival airport.
</ParamField>

<ParamField query="airline" type="string" required>
  IATA airline code (e.g. `AZ` for ITA Airways, `BA` for British Airways).
</ParamField>

<ParamField query="date" type="string" required>
  Departure date in `YYYY-MM-DD` format.
</ParamField>

<ParamField query="news" type="boolean" default="false">
  If `true`, includes a live news feed of disruption reports for the route in the response.
</ParamField>

<ParamField query="api_key" type="string" required>
  Your API key.
</ParamField>

## Response

<ResponseField name="score" type="integer">
  Risk Score from 0 (lowest risk) to 100 (highest risk).
</ResponseField>

<ResponseField name="score_linear" type="integer">
  Statistical-only score before ML blending.
</ResponseField>

<ResponseField name="score_ml" type="integer">
  ML model prediction (0–100). `null` if model unavailable.
</ResponseField>

<ResponseField name="ml_available" type="boolean">
  Whether the ML model contributed to this score.
</ResponseField>

<ResponseField name="label" type="string">
  Human-readable risk label: `Low`, `Moderate`, `High`, or `Very High`.
</ResponseField>

<ResponseField name="recommendation" type="string">
  One-sentence actionable recommendation based on the risk level and top driver.
</ResponseField>

<ResponseField name="input" type="object">
  Echo of the query parameters: `origin`, `destination`, `airline`, `flight_date`.
</ResponseField>

<ResponseField name="stats" type="object">
  Historical statistics for this route/airline combination.

  <Expandable title="stats fields">
    <ResponseField name="delay_rate_pct" type="float">
      Historical percentage of flights delayed > 30 min.
    </ResponseField>

    <ResponseField name="cancel_rate_pct" type="float">
      Historical cancellation rate percentage.
    </ResponseField>

    <ResponseField name="avg_delay_min" type="float">
      Average delay in minutes for delayed flights (> 30 min).
    </ResponseField>

    <ResponseField name="n_flights" type="integer">
      Number of historical flights used to compute the score.
    </ResponseField>

    <ResponseField name="confidence_pct" type="integer">
      Confidence in the score (0–100), based on historical data volume.
    </ResponseField>

    <ResponseField name="congestion_dep" type="float">
      Congestion score for the departure airport (0.0–1.0).
    </ResponseField>

    <ResponseField name="congestion_arr" type="float">
      Congestion score for the arrival airport (0.0–1.0).
    </ResponseField>

    <ResponseField name="ml_probability" type="float">
      ML-estimated probability of delay > 30 min, as a percentage. `null` if unavailable.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="components" type="array">
  Sorted list of risk factor contributions (highest first).

  <Expandable title="Component object">
    <ResponseField name="key" type="string">
      Factor key: `delay_rate`, `cancel_rate`, `congestion`, `weather`, `seasonality`, `event_risk`.
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the factor.
    </ResponseField>

    <ResponseField name="value" type="float">
      Raw factor value (0.0–1.0).
    </ResponseField>

    <ResponseField name="label" type="string">
      Qualitative label: `Low`, `Moderate`, `High`, or `Very High`.
    </ResponseField>

    <ResponseField name="contribution" type="float">
      Contribution to the final score in score points.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="weather_dep" type="object">
  Weather risk at the departure airport for the requested date.

  <Expandable title="Weather object">
    <ResponseField name="score" type="float">Weather risk score 0.0–1.0.</ResponseField>
    <ResponseField name="condition" type="string">Human-readable condition (e.g. `Clear`, `Rain`, `Snow`).</ResponseField>
    <ResponseField name="temp" type="float">Temperature in °C. `null` if unavailable.</ResponseField>
    <ResponseField name="wind" type="float">Max wind speed in km/h. `null` if unavailable.</ResponseField>
    <ResponseField name="precip" type="float">Max precipitation in mm. `null` if unavailable.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="weather_arr" type="object">
  Weather risk at the arrival airport. Same structure as `weather_dep`.
</ResponseField>

<ResponseField name="data_source" type="string">
  Which data tier was used: `exact` (origin+dest+airline match), `route_any_airline` (fallback — any airline on the route), or `no_data`.
</ResponseField>

<ResponseField name="airline_info" type="object">
  Airline metadata: `name` (full name), `country`.
</ResponseField>

<ResponseField name="origin_info" type="object">
  Airport metadata for origin: `name`, `city`, `country`.
</ResponseField>

<ResponseField name="dest_info" type="object">
  Airport metadata for destination: `name`, `city`, `country`.
</ResponseField>

<ResponseField name="news" type="array">
  Present only when `news=true`. Array of disruption reports — see [Route News](/api-reference/news) for the item schema.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.airrating.io/api/score?origin=FCO&dest=LHR&airline=AZ&date=2026-04-10&api_key=YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.get(
      "https://app.airrating.io/api/score",
      params={
          "origin": "FCO",
          "dest": "LHR",
          "airline": "AZ",
          "date": "2026-04-10",
          "api_key": "YOUR_API_KEY",
      }
  )
  data = response.json()
  print(f"Score: {data['score']} — {data['label']}")
  print(f"Delay rate: {data['stats']['delay_rate_pct']}%")
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    origin: "FCO",
    dest: "LHR",
    airline: "AZ",
    date: "2026-04-10",
    api_key: "YOUR_API_KEY",
  });

  const res = await fetch(`https://app.airrating.io/api/score?${params}`);
  const data = await res.json();
  console.log(`Score: ${data.score} — ${data.label}`);
  ```
</CodeGroup>

```json Response theme={null}
{
  "score": 62,
  "score_linear": 65,
  "score_ml": 52,
  "ml_available": true,
  "label": "High",
  "recommendation": "Elevated risk — check alternatives. Main driver: Historical Delay Rate.",
  "input": {
    "origin": "FCO",
    "destination": "LHR",
    "airline": "AZ",
    "flight_date": "2026-04-10"
  },
  "stats": {
    "delay_rate_pct": 31.0,
    "cancel_rate_pct": 4.2,
    "avg_delay_min": 28.4,
    "n_flights": 312,
    "confidence_pct": 84,
    "congestion_dep": 0.52,
    "congestion_arr": 0.78,
    "ml_probability": 38.0
  },
  "components": [
    { "key": "delay_rate", "name": "Historical Delay Rate", "value": 0.31, "label": "High", "contribution": 18.6 },
    { "key": "congestion", "name": "Airport Congestion", "value": 0.65, "label": "Moderate", "contribution": 9.75 },
    { "key": "weather", "name": "Weather", "value": 0.22, "label": "Low", "contribution": 4.4 },
    { "key": "seasonality", "name": "Seasonality", "value": 0.3, "label": "Low", "contribution": 3.0 }
  ],
  "weather_dep": { "score": 0.18, "condition": "Partly cloudy", "temp": 14.0, "wind": 22.0, "precip": 0.0 },
  "weather_arr": { "score": 0.27, "condition": "Rain", "temp": 10.0, "wind": 35.0, "precip": 2.1 },
  "data_source": "exact",
  "data_provider": "aviation_edge",
  "airline_info": { "name": "ITA Airways", "country": "Italy" },
  "origin_info": { "name": "Leonardo da Vinci–Fiumicino Airport", "city": "Rome", "country": "Italy" },
  "dest_info": { "name": "Heathrow Airport", "city": "London", "country": "United Kingdom" }
}
```

## Score interpretation

| Score  | Label     | Recommendation                                                     |
| ------ | --------- | ------------------------------------------------------------------ |
| 0–30   | Low       | Safe to book, low historical delay rate                            |
| 31–55  | Moderate  | Some risk — consider flexible fare and monitor closer to departure |
| 56–74  | High      | Elevated risk — check alternatives or add buffer time              |
| 75–100 | Very High | High disruption probability — evaluate alternatives                |

## Scoring formula

```
score = 70% × statistical_score + 30% × ml_probability × min(1.0, confidence × 2)
```

The ML weight reduces automatically when historical data volume is low (`confidence_pct` \< 50), keeping the score grounded in observed outcomes.