Calculate one or more forecast hours and return areas that meet a fixed-value or percentile threshold as GeoJSON. Omit forecast_hours to calculate every available hour. See About Custom Calculations for calculation syntax and examples.
| Name | Type | Description |
|---|---|---|
| model Required | string | Weather model to use. Allowed: wm-6, wm-6-3km |
| initialization_time Optional | string (ISO 8601) | The initialization time for the forecast. Default: latest complete run |
| forecast_hours Optional | integer | integer[] | One nonnegative forecast hour or a nonempty list of nonnegative forecast hours. Omit to evaluate every available forecast hour. Unit: hours |
| calculation Required | string | Custom calculation expression whose result will be thresholded. See About Custom Calculations for syntax and examples. |
| bounds Required | object | Bounding box used to calculate the threshold and clip the returned polygons. |
| min_latitude Required | number | Southern edge of the bounding box. Must be less than max_latitude. Range: −90° to 90° |
| max_latitude Required | number | Northern edge of the bounding box. Range: −90° to 90° |
| min_longitude Required | number | Western edge of the bounding box. Must be less than max_longitude. The bounding box cannot cross the dateline. Range: −180° to 180° |
| max_longitude Required | number | Eastern edge of the bounding box. Range: −180° to 180° |
| threshold Required | object | An absolute or percentile threshold. |
| kind Required | string | Kind of threshold. Allowed: absolute, percentile |
| value Conditional | number | Cutoff value. Required when kind is absolute. |
| comparison Conditional | string | Side of the cutoff to select. Required when kind is absolute. Allowed: at_or_above, at_or_below |
| percentile Conditional | number | Percentage selected from the end named by direction. For the highest 10%, use percentile: 10 and direction: "highest". Required when kind is percentile. Range: greater than 0, up to 100 |
| direction Conditional | string | End of the distribution to select from. Required when kind is percentile. Allowed: lowest, highest |
| Selection | Example | Behavior |
|---|---|---|
| One hour | "forecast_hours": 6 | Evaluate the calculation at forecast hour 6. |
| Specific hours | "forecast_hours": [0, 6, 12] | Evaluate the calculation at the listed forecast hours. |
| All hours | Omit forecast_hours | Evaluate the calculation at every available forecast hour. |
Each selected forecast hour is calculated separately. Hours that do not have all required input data are skipped, and results for the remaining hours are returned. If no selected hour can be calculated, the request returns HTTP 400.
| Kind | Example | Behavior |
|---|---|---|
| absolute | {"kind": "absolute", "value": 0, "comparison": "at_or_below"} | Select finite values at or below 0. Use at_or_above to select values at or above the cutoff. |
| percentile | {"kind": "percentile", "percentile": 10, "direction": "lowest"} | Calculate the 10th percentile from finite values inside bounds, then select values at or below that cutoff.
To select the highest 10% of values, use Percentile cutoffs use linear interpolation. Tied values can make the selected area larger than the requested percentage. |
Both absolute and percentile thresholds include values equal to the cutoff.
A successful request returns a GeoJSON FeatureCollection. Each output grid with matching cells produces one MultiPolygon feature. Output grids without matching cells are omitted.
| Name | Type | Description |
|---|---|---|
| type | string | Always FeatureCollection. |
| model | string | Model whose forecast output was used. |
| initialization_time | string (ISO 8601) | The forecast initialization time. |
| forecast_zero | string (ISO 8601) | Valid time of forecast hour 0. It can differ from initialization_time. |
| forecast_hours | integer[] | The requested forecast hours, returned as an array. Unit: hours |
| calculation | string | The calculation evaluated by the request. |
| output_calculations | string[] | The calculation for each output grid. Each feature repeats its matching calculation in properties.output_calculation. |
| forecast_hour_errors | object[] | Requested forecast hours that could not be calculated. Empty when every requested hour succeeds. |
| forecast_hour | integer | The forecast hour that could not be calculated. Unit: hours |
| code | string | Machine-readable reason for the failure. |
| message | string | Human-readable description of the failure. |
| threshold | object | Threshold supplied in the request. |
| features | object[] (GeoJSON Feature) | One feature for each output grid that contains matching cells. |
| type | string | Always Feature. |
| geometry | object (GeoJSON MultiPolygon) | WGS84 geometry using [longitude, latitude] coordinates. |
| properties | object | Forecast-hour, output-grid, and validity metadata for the feature. |
| forecast_hour | integer | The successfully calculated forecast hour. Unit: hours |
| output_calculation | string | The calculation used to produce this output grid. |
| valid_from | string (ISO 8601) | null | The start of the grid's valid time range. |
| valid_to | string (ISO 8601) | null | The end of the grid's valid time range. |