# Retrieve forecast regions

`GET https://contrails.googleapis.com/v2/regions`: Get contrail avoidance
regions in GeoJSON multipolygon format.

If successful, the response will be a `FeatureCollection` in GeoJSON format.

Returned contrail avoidance regions in polygon format are rated by severity
levels, ranging from 1 to 4 for each flight level. The higher the value, the
more severe the contrail.

## Query parameters

| Parameters ||
|---|---|
| `time` | `string` Required. Time of request. Format: ISO 8601 datetime string OR Unix epoch integer Example: `2026-01-20T21:00:00Z` |
| `flightLevel[]` | `integer` Optional. Flight levels to return. If no flight level is specified, then all flight levels are included. Format: Flight levels in hectofeet; \[270, 280, 290, 300, 310, 320, 330, 340, 350, 360, 370, 380, 390, 400, 410, 420, 430, 440\] Example: `[270, 280, 290, 300]` |
| `threshold` | `integer` Optional. Minimum severity level threshold. Setting this field returns only regions with severity greater than or equal to the threshold. Format: Valid values range from 1 to 4 (inclusive). |
| `aircraftClass` | `string` Optional. Aircraft class. Currently, only `default` is supported. |

## Examples

- To retrieve all contrail avoidance regions for a specific point in time:

      response = requests.get(
        url="https://contrails.googleapis.com/v2/regions",
        params={"time": 2026-01-27T12:00:00Z},
        headers={"x-goog-api-key": API_KEY},
      )

  The GeoJSON response lists all contrail avoidance regions in polygon format:

  |   | geometry | flight_level | threshold | time | forecast_reference_time | aircraft_class |
  |---|---|---|---|---|---|---|
  | **0** | MULTIPOLYGON Z (((166.25 81.12 8229.6, 168.37 ... | 270 | 1 | 2026-01-28T20:00:00+00:00 | 2026-01-27T08:00:00+00:00 | default |
  | **1** | MULTIPOLYGON Z (((92.38 45.5 8229.6, 93 46.62 ... | 270 | 2 | 2026-01-28T20:00:00+00:00 | 2026-01-27T08:00:00+00:00 | default |
  | **2** | MULTIPOLYGON Z (((83.38 65 8229.6, 84 66.12 82... | 270 | 3 | 2026-01-28T20:00:00+00:00 | 2026-01-27T08:00:00+00:00 | default |
  | **3** | MULTIPOLYGON Z (((57.38 76 8229.6, 57.75 76.88... | 270 | 4 | 2026-01-28T20:00:00+00:00 | 2026-01-27T08:00:00+00:00 | default |
  | **4** | MULTIPOLYGON Z (((162.38 79 8534.4, 162.75 79.... | 280 | 1 | 2026-01-28T20:00:00+00:00 | 2026-01-27T08:00:00+00:00 | default |

- To retrieve contrail avoidance regions limited to specific flight levels, with time specified as a Unix epoch integer:

      response = requests.get(
        url="https://contrails.googleapis.com/v2/regions",
        params={
          "time": 1768942800,
          "flightLevel": [300,310,320,330]
        },
        headers={"x-goog-api-key": API_KEY},
      )

- To retrieve contrail avoidance regions limited to specific flight levels and
  equal or above a severity level threshold of 3:

      response = requests.get(
        url="https://contrails.googleapis.com/v2/regions",
        params={
          "time": 2026-01-27T12:00:00Z,
          "flightLevel": [300,310,320,330],
          "threshold": 3
        },
        headers={"x-goog-api-key": API_KEY},
      )