Nowcast API Guide

Integration Fact Sheet

Auth Type	Base URL	Protocol
API Key	https://api.forecast.metservice.com/nowcast/v1	REST

Welcome to the Nowcast API! This guide provides everything you need to understand and integrate our near real-time, short-term weather forecasts.

For a complete, interactive list of all endpoints, parameters, and response schemas, please refer to our API Reference. For product information and pricing, see the Nowcast API Product Page.

Core Concepts

The Nowcast API provides high-frequency forecasts by using machine learning to integrate live weather observations, resulting in higher accuracy for short-term predictions.

High Frequency: Forecasts are generated every 10 minutes.
Short Horizon: Each forecast predicts out to a 6-hour horizon.
High Resolution: Predictions are available in 10-minute intervals.

Understanding Locations

The Nowcast API provides forecasts for specific physical locations where we have weather observation stations. Each location has:

A unique S-ID (e.g., SNZ123456) which is our internal identifier for the forecast location
One or more observation station ID synonyms (e.g., NZWN for Wellington Airport) that provide the input data
Precise latitude and longitude coordinates

Because nowcasts are generated using real-time observations, forecasts are only available at locations with active weather stations. This means:

Not all locations have all variables (depends on installed sensors)
Different locations may have measurements at different heights
The quality of the nowcast depends on the quality and availability of observations

You can find all available locations, along with their capabilities, on our Available Locations page.

This nowcast data is ideal for immediate, confident decision-making and complements the longer-range data from our Point Forecast API and our enhanced Probability Distribution (ePD) product (Contact Sales) along side the observation data from the our Observations APIs

How It Works

The nowcast model runs on a strict 10-minute schedule. A new forecast is generated only if new observation data was available during the previous time interval. The forecast generation process runs on the 10-minute mark, meaning we target producing a new forecast 2 minutes past the interval (e.g., 10:02). See our recommended polling strategies for the best way to retrieve the latest data.

Nowcast Forecast Structure
       New Forecast Every 10min
           ↓
10:00  [F1] 6hr forecast →→→→→→→→→→→→→→→→→→→→→ (until 16:00)
10:10  [F2] 6hr forecast →→→→→→→→→→→→→→→→→→→→→ (until 16:10)
10:20  [F3] 6hr forecast →→→→→→→→→→→→→→→→→→→→→ (until 16:20)
       ⋮
       
Detail of a Single 6-hour Forecast:
[F1] 10:00→10:10→10:20→10:30→...→15:40→15:50→16:00
      ↑     ↑     ↑     ↑    ⋯    ↑     ↑     ↑
      Predictions at 10-minute intervals (36 points)

Forecast Variables

The API provides forecasts for the following weather variables at different heights above ground level. For the precise data model and units, please see the schema in the API Reference.

Air Temperature: Temperature measurements, typically at 2m above ground
Wind Speed: Wind speed measurements, typically at 10m above ground
Wind from Direction: Wind direction in degrees from true north, typically at 10m above ground

Accuracy

The Nowcast system provides the highest possible accuracy in the short term by incorporating the absolute latest weather observations. This corrects for changes in the atmosphere that occur between the fixed run times of standard global models. As a result, the Nowcast system shows a significant advantage, particularly in the first two hours of the forecast horizon, where it consistently demonstrates higher accuracy compared to standard NWP models.

Evaluating forecast accuracy is more than just looking at a single number. A simple average error (or bias) can be misleading; for example, a forecast that is 2 degrees too high one day and 2 degrees too low the next has an average error of zero, but was wrong both days. For this reason, we focus on Mean Absolute Error (MAE), which measures the average size of an error regardless of its direction. This gives a much better real-world indication of the forecast's typical performance.

Getting Started: Your First Nowcast

Ready to make your first API call? This short tutorial will walk you through it.

1. Get Your API Key

You'll need an API key to use the API. If you don't have one, contact our team at api-queries@metservice.com to obtain one. Your key provides access to all MetService APIs you're subscribed to.

For detailed information on obtaining and using your key, see the main Authentication Guide.

2. Find a Location

Nowcasts are tied to physical weather observation stations. Each location has a unique MetService Location S-ID (e.g., SiiNNNNNN) that you'll use in your API requests. This identifier:

Links your request to a specific observation station
Determines which weather variables are available
Controls what data your API key can access

You can find all currently available forecast locations on the Available Locations page. The page provides:

A searchable list of all locations
The variables available at each location
The observation station ID synonyms associated with each location

3. Make the API Call

Use the location_id to call the /points/{location_id} endpoint. This will retrieve the latest 6-hour nowcast for that location. By default, the API returns data in a standard JSON format, which is optimized for most use cases.

Here’s a basic example using cURL:

Example: Get a Point Nowcast
curl -H "apikey: YOUR_API_KEY" "https://api.forecast.metservice.com/nowcast/v1/points/SiiNNNNNN"

Example Response
```json title="Example Response"
{
  "metadata": {
    "location": {
      "id": "SNZ123456",
      "name": "Wellington International Airport",
      "latitude": -41.32,
      "longitude": 174.80,
      "observation_station_ids": ["NZWN"],
      "elevation": 10.5,
      "offset_to_utc": 12.0
    },
    "units": {
      "air_temperature": "Celsius",
      "wind_speed": "km/h",
      "wind_from_direction": "degrees"
    }
  },
  "nowcast_data": [
    {
      "time": "2023-10-27T14:00:00Z",
      "air_temperature": 15.2,
      "wind_speed": 25.5,
      "wind_from_direction": 330
    },
    {
      "time": "2023-10-27T14:10:00Z",
      "air_temperature": 15.1,
      "wind_speed": 26.1,
      "wind_from_direction": 332
    },
    {
      "time": "2023-10-27T14:20:00Z",
      "air_temperature": 15.0,
      "wind_speed": 26.5,
      "wind_from_direction": 335
    }
  ]
}

This request will return a standard JSON object containing the metadata (including detailed location info) and forecast data. The API provides two optional parameters to customize your request:
* Use `variables` to request only specific weather variables (e.g., `?variables=air_temperature,wind_speed`)
* Use `from` to retrieve a forecast from a specific time in the last 24 hours (e.g., `?from=2023-10-27T12:00:00Z`)

For a full breakdown of the request parameters and a detailed example of the response body, see the [**`GET /points/{location_id}`**](/api-reference/nowcast) endpoint in the [API Reference](/api-reference/nowcast).

If you need to integrate with a GIS system, plot the nowcast location directly onto an interactive map or just prefer a GeoJSON format, you can including an `Accept` header in your request to modify the response format.

```bash title="Example: Specify the GeoJSON response format" 
curl -H "apikey: YOUR_API_KEY"   
     -H "Accept: application/geo+json"   
     "[https://api.forecast.metservice.com/nowcast/v1/points/SiiNNNNNN"

Working with GeoJSON for Mapping

The application/geo+json format is a powerful open standard for representing geographic features. When you request your data in this format, it's easy to plot the nowcast location directly onto interactive maps using popular libraries like Leaflet, Mapbox, or the Google Maps API.

Using the API

Requesting the Latest Forecast

To get the latest data efficiently, you can choose one of two strategies based on your application's needs.

Strategy 1: Simple Scheduled Poll (Good)

This is the simplest approach and is sufficient for many use cases.

How it works: Schedule a single API call to run every 10 minutes, precisely at the 2-minute-past mark (e.g., at 10:02, 10:12, 10:22, etc.). To be safe, you might add a few seconds of buffer and poll at xx:02:05.
Pros:
- Extremely simple to implement (e.g., a standard cron job).
- Minimal API calls (only 6 per hour).
Cons:
- Can be brittle. It relies on your system's clock being reasonably synchronized with the API server's clock and assumes minimal network latency. If your request arrives a few seconds too early, you will miss the update and have to wait another 10 minutes.

Strategy 2: Targeted Polling Window (Best Practice)

This is the most resilient strategy and is recommended for production systems where getting the latest data as soon as possible is critical.

How it works: Instead of polling constantly, you open a "polling window" that starts at the 10-minute mark and closes at 2 minutes and 15 seconds past.
1. Wait for the Interval: Your application waits for the known 10-minute mark (e.g., 10:10:00, 10:20:00, etc.).
2. Open the Polling Window: Start polling the API at a high frequency (e.g., every 15 seconds).
3. Check the Timestamp: On each poll, compare the time of the first data interval with the start time of the last forecast you processed. Since the forecast window rolls forward every 10 minutes, a change in the first timestamp indicates a new model run.
4. Close the Window: If the start time has updated (e.g., from 10:00 to 10:10), process the new data and stop polling until the next 10-minute cycle. If you reach xx:02:15 and the timestamp hasn't changed, stop polling and wait for the next cycle.
Pros:
- Maximum Timeliness: You get the forecast almost the instant it becomes available.
- Maximum Efficiency: You avoid making any API calls for most of the 10-minute cycle.
- Full Resilience: It gracefully handles minor variations in processing time or network latency.

Polling Window Timeline
◄────────────── A Single 10-Minute Cycle (e.g., 10:10 to 10:20) ──────────────►

|-----------------|-----------------------------|------------------------------|
10:10:00         ~10:12:00                    10:12:15                      10:20:00
  ▲                 ▲                           ▲                              ▲
  |                 |                           |                              |
Start of      New forecast is             Polling window closes.         Next cycle
cycle.        GENERALLY available.          If no update is found,         begins.
BEGIN POLLING
(e.g. every 15s)

[Expected Sequence]
1. At 10:12:00, start polling.
   - API call -> receive data starting at 10:00 (OLD).
2. Keep polling...
   - API call -> receive data starting at 10:10 (NEW).
3. SUCCESS! Process the new data and STOP POLLING until 10:22:00.

Example Logic (Targeted Polling Window)

// -- State variable to hold the start time of the last forecast you processed --  
last_known_start_time = null

// -- Main function to be scheduled --  
FUNCTION start_polling_window:  
    // This function should be triggered by a scheduler (e.g., cron) every 10 minutes.  
    // It initiates a high-frequency polling loop for a short duration.

    polling_end_time = current_time() + 135 seconds // 2 minutes, 15 seconds timeout

    LOOP WHILE current_time() < polling_end_time:  
    LOOP WHILE current_time() < polling_end_time:  
        response = CALL_API("/points/{location_id}")  
        new_start_time = response.nowcast_data[0].time // Check the first interval's time

        IF new_start_time IS NOT last_known_start_time THEN  
            // New data is available!  
            process_new_data(response.nowcast_data)  
            last_known_start_time = new_start_time  
            PRINT("Forecast updated for window starting: " + new_start_time)

            // Exit the loop immediately since we have the latest data.  
            BREAK LOOP  
        END IF

        // Wait before the next poll to avoid overwhelming the API.  
        WAIT 15 seconds  
    END LOOP  
END FUNCTION

Checking API Status

For general health and availability monitoring, you can make a simple GET request to the /health endpoint. This endpoint does not require authentication with an API key and is designed to provide a quick check on the API's operational status.

This endpoint will return a 200 OK status code with a simple JSON object if the API is online.

Example: Check the API Status
curl "https://api.forecast.metservice.com/nowcast/v1/health"

Requesting Recent Data

The API allows you to retrieve historical nowcasts from the last 24 hours using the at parameter. When you specify a timestamp, you receive the forecast that would have been available if you had called the API at that past time:

The API returns a complete 6-hour forecast that was available at that time
Each response contains 36 intervals (one every 10 minutes)
The intervals start at the requested time and extend 6 hours into the future
Timestamps must be within the last 24 hours from the current time

Example: Get a specific historical nowcast
# Returns the 6-hour forecast that was generated and valid at 08:00
curl -H "apikey: YOUR_API_KEY" "https://api.forecast.metservice.com/nowcast/v1/points/SiiNNNNNN?at=2023-10-27T08:00:00Z"

To retrieve multiple missed windows, you'll need to make separate requests for each time you're interested in. For instance, to analyze how the forecast evolved:

Example: Retrieving multiple forecast windows
# Get forecast from 08:00 (predicting 08:00-14:00)
curl ... "?at=2023-10-27T08:00:00Z"

# Get forecast from 09:00 (predicting 09:00-15:00)
curl ... "?at=2023-10-27T09:00:00Z"

# Get forecast from 10:00 (predicting 10:00-16:00)
curl ... "?at=2023-10-27T10:00:00Z"

Historical Data Access

For data older than 24 hours or for bulk historical data access, please see the Historical Data section.

Error Handling

The Nowcast API uses standard HTTP status codes to indicate the success or failure of a request. Your application should be prepared to handle common 4xx client-side errors.

For a comprehensive guide to all platform error codes and response formats, please see the main Error Handling page.

Rate Limiting and Fair Use

The Nowcast API implements platform-wide rate limiting to ensure service stability and availability for all users. Unlike per-client rate limits, these are shared limits that protect the entire platform.

How It Works:

Rate limits are applied at the platform level, not per individual API key
Limits are designed to accommodate normal usage patterns, including the recommended polling strategies described above
If the platform experiences excessive load, requests may be throttled with a 429 Too Many Requests response

Fair Use Policy:

All users are expected to follow fair use practices:

Use the recommended polling strategies (targeted polling window or scheduled polling)
Avoid unnecessary requests (e.g., don't poll continuously)
Implement exponential backoff when receiving 429 responses
Cache responses appropriately for your use case

The platform is designed to support reasonable usage patterns. If you have requirements that may exceed typical usage, please contact our team at api-queries@metservice.com to discuss your needs.

Handling Rate Limit Responses:

If you receive a 429 response:

Check for the Retry-After header, which indicates how long to wait (in seconds)
Implement exponential backoff if Retry-After is not provided
Review your polling strategy to ensure it aligns with our recommendations

For detailed information on error responses, please see the main Error Handling page.

Handling Missing Data and Gaps

Occasionally, a forecast interval may not have a value for a specific variable (e.g., air_temperature might be null). This is expected behavior when observation data is temporarily unavailable. This is done explicitly to prevent forecast errors or inaccurate forecasts being silently ingested. Your application should check for and catch null values.

Depending on your use case you might want to log these, pass it on to an alerting system, ignore them, or use the previous forecast value. Typically these null values are temporary due to an observation missing a cut off time, however we monitor observations for extended outages and attempt to resolve issues as quickly as we can. If you are providing us with the observations we encourage you to troubleshoot them on your end first before contacting us.

Understanding Altitude Data

Weather variables are provided at a standard reference height for that location. Unlike raw model logic which might offer multiple heights, the Nowcast API simplifies this to the most relevant operational observation for the site.

Air Temperature: Typically measured at 2m above ground.
Wind: Typically measured at 10m above ground.

The specific unit for each variable is provided in the metadata.units object.

Locations and Authorisation

The Nowcast API is priced on a per-location basis. Your API key is authorised for a specific set of locations agreed upon during key setup.

Location-Based Access: Each API key is configured to access specific S-IDs
Single Location Requests: Each API call can only specify one location_id
Unauthorised Access: Requesting a location your key isn't authorised for will return a 403 Forbidden error
Adding Locations: To access additional locations, contact our Sales Team

Historical Data

MetService can provide historical weather observations and nowcast data to support verification and research.

Historical Observations: Available for most locations in our network.
Historical Nowcasts: This is a more complex process requiring re-computation of forecasts and is available as a bespoke service.

Please contact the Sales Team to discuss your historical data needs.

Core Concepts​

Understanding Locations​

How It Works​

Forecast Variables​

Accuracy​

Getting Started: Your First Nowcast​

1. Get Your API Key​

2. Find a Location​

3. Make the API Call​

Using the API​

Requesting the Latest Forecast​

Strategy 1: Simple Scheduled Poll (Good)​

Strategy 2: Targeted Polling Window (Best Practice)​

Example Logic (Targeted Polling Window)​

Checking API Status​

Requesting Recent Data​

Error Handling​

Rate Limiting and Fair Use​

Handling Missing Data and Gaps​

Understanding Altitude Data​

Locations and Authorisation​

Historical Data​