Nowcast API Guide
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.,
NZWNfor 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). The response metadata includes both the model_run_time and the latest_observation_time so you can see the precise timestamp of the input data used for the forecast. See our recommended polling strategies for the best way to retrieve the latest data.
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:
curl -H "apikey: YOUR_API_KEY" "https://api.forecast.metservice.com/nowcast/v1/points/SiiNNNNNN"
{
"location": {
"id": "SNZ123456",
"name": "Wellington International Airport",
"latitude": -41.32,
"longitude": 174.80,
"observation_station_ids": ["NZWN"]
},
"metadata": {
"conventions": "CF-1.12",
"model_run_time": "2023-10-27T13:55:00Z",
"latest_observation_time": "2023-10-27T13:50:00Z",
"variable_units": {
"air_temperature": "Celsius",
"wind_speed": "km/h",
"wind_from_direction": "degrees"
}
},
"nowcast": [
{
"time": "2023-10-27T14:00:00Z",
"air_temperature": {
"at_2m": { "value": 15.2 },
"at_10m": { "value": 14.8 }
},
"wind_speed": {
"at_2m": { "value": 12.5 },
"at_10m": { "value": 18.2 }
},
"wind_from_direction": {
"at_2m": { "value": 320.0 },
"at_10m": { "value": 315.5 }
}
}
]
}
This request will return a standard JSON object containing the location, metadata, and forecast data. The API provides two optional parameters to customize your request:
- Use
variablesto request only specific weather variables (e.g.,?variables=air_temperature,wind_speed) - Use
fromto 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} endpoint in the API Reference.
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.
curl -H "apikey: YOUR_API_KEY"
-H "Accept: application/geo+json"
"[https://api.forecast.metservice.com/nowcast/v1/points/SiiNNNNNN"
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.
- Wait for the Interval: Your application waits for the known 10-minute mark (e.g., 10:10:00, 10:20:00, etc.).
- Open the Polling Window: Start polling the API at a high frequency (e.g., every 15 seconds).
- Check the Timestamp: On each poll, compare the
model_run_timein the response metadata with the timestamp you last processed. - Close the Window: If the
model_run_timehas updated, process the new data and stop polling until the next 10-minute cycle. If you reachxx:02:15and 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.
◄────────────── 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 stop and wait.
(e.g. every 15s)
[Expected Sequence]
1. At 10:10:00, start polling.
- API call -> receive data with OLD `model_run_time`.
2. Keep polling...
- API call -> receive data with NEW `model_run_time`.
3. SUCCESS! Process the new data and STOP POLLING until 10:20:00.
Example Logic (Targeted Polling Window)
// -- State variable to hold the timestamp of the last data you processed --
last_known_run_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:
response = CALL_API("/points/{location_id}")
new_run_time = response.metadata.model_run_time
IF new_run_time IS NOT last_known_run_time THEN
// New data is available!
process_new_data(response.nowcast)
last_known_run_time = new_run_time
PRINT("Forecast updated at: " + new_run_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 /status 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.
curl "https://api.forecast.metservice.com/nowcast/v1/status"
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
# 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:
# 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"
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 Requestsresponse
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
429responses - 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-Afterheader, which indicates how long to wait (in seconds) - Implement exponential backoff if
Retry-Afteris 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 measured and predicted at different heights above ground level, represented by keys like at_2m or at_10m. Important considerations when working with altitude data:
- Variable Altitudes: Different locations may have sensors at different heights. Don't assume specific altitudes will be available.
- Common Heights: Temperature is typically measured at 2m, while wind measurements are often at 10m (international standard heights).
- Handling Multiple Altitudes: Your application should:
- Check which altitudes are available in the first response
- Use the most appropriate altitude for your use case (e.g., 2m for human comfort, 10m for wind energy)
- Handle cases where your preferred altitude might not be available
// Helper function to get temperature at a preferred height (e.g., 2m)
// Falls back to closest available height if preferred is not available
FUNCTION get_temperature_at_best_height(interval, preferred_height):
temps = interval.air_temperature
IF temps IS NULL THEN
RETURN NULL // No temperature data available
// Get list of available heights (e.g., [2, 10])
heights = []
FOR EACH key IN temps:
height = extract_number_from_key(key) // e.g., "at_2m" -> 2
ADD height TO heights
IF heights IS EMPTY THEN
RETURN NULL // No heights available
IF preferred_height EXISTS IN heights THEN
// Preferred height exists, use it
RETURN temps["at_" + preferred_height + "m"].mean
ELSE
// Find closest available height
closest = find_closest_number(preferred_height, heights)
RETURN temps["at_" + closest + "m"].mean
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 Forbiddenerror - 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.