Skip to main content

1-Minute Observations API CLASSIC

Classic API

The 1-Minute Observations API is a stable, widely-used Classic API. Because it has specific authentication, error handling, and rate limits, the broad Platform Guides do not apply. Please follow the in-line documentation provided in this guide.

Note: This API is currently only available for commercial use. If you would like to be notified when the free tier becomes available, please join the waitlist.

Integration Fact Sheet
Auth TypeAPI AccessBase URLProtocol
API Key / BearerManual Requesthttps://api.metservice.com/observations/nz/1-minuteREST

VariablesCoverageHorizonInterval
Air Temp, Wind Speed/Direction, Dew Point, Rainfall, Pressure (Station/MSL), Visibility, Radiation (Global/Net), Earth Temps, Road Conditions/Temps/FilmNZ Observation StationsReal-time + 60 days Historical1-minute

The 1-Minute Observations API provides access to real-time weather observation data from MetService's network of Automatic Weather Stations, Road Sensors, and Airport Runway Sensors across New Zealand.

Overview​

This API delivers 1-minute observation data with a 60-day retention period from the time of observation. The data is collected from various sensor types including:

  • Automatic Weather Stations - Standard meteorological observations
  • Road Sensors - Road surface and atmospheric conditions
  • Airport Runway Sensors - Aviation-specific weather data

Key Features​

  • Real-time Data: Observations updated every minute
  • 60-Day History: Access to historical data up to 60 days old
  • Multiple Formats: JSON and CF-JSON (with field descriptions)
  • Flexible Queries: Latest, time-range, and historical data access
  • Station Metadata: Complete station information and identifiers

Authentication​

To use this API, you must first Request Access to receive an API Key.

The API supports two authentication methods:

API Key Authentication​

  • By provision of an API Key provided on an HTTP header of type apikey
  • API Key authentication is performed against the Gateway Developer Portal database using standard gateway assertions
  • An API Key is assigned when an Application is configured within the Gateway Developer Portal for the API customer
  • The API customer's Application must have this API assigned to it for use
curl -H "apikey: your-api-key-here" \
  "`https://api.metservice.com/observations/nz/1-minute/weatherStation"`

Bearer Token Authentication​

  • By provision of a Bearer token provided on an HTTP header of type Authorization
  • Bearer token authentication is performed by validating and decoding against a JWKS (JSON Web Key Set)
  • Currently an OKTA and MetConnect JWKS are supported
  • The bearer token will have been assigned when the API user or application authenticated against another Authentication service
curl -H "Authorization: Bearer your-bearer-token-here" \
  "`https://api.metservice.com/observations/nz/1-minute/weatherStation"`

Quick Start​

  1. Get API Access: Submit a request via the Request Access form.
  2. List Available Stations: GET /weatherStation
  3. Get Latest Data: GET /weatherStation/{stationId}/latest
  4. Query Historical Data: GET /weatherStation/{stationId}/range/{from}/{to}

Example Calls​

# Get list of available stations
curl --location --request GET '`https://api.metservice.com/observations/nz/1-minute/weatherStation'` \
  --header 'Authorization: Bearer <your-bearer-token>'

# Get latest data with specific variables
curl --location --request GET '`https://api.metservice.com/observations/nz/1-minute/weatherStation/93968/latest?format=json&vars=airtemp_01mnavg,windspd_01mnavg'` \
  --header 'Authorization: Bearer <your-bearer-token>'

# Get last 10 minutes of data in cf-json format
curl --location --request GET '`https://api.metservice.com/observations/nz/1-minute/weatherStation/NZKTA/last/10/minutes?format=cf-json'` \
  --header 'apikey: <your-api-key>'

# Get data for a specific time range
curl --location --request GET '`https://api.metservice.com/observations/nz/1-minute/weatherStation/93110/range/2020-06-19T04:00:00Z/2020-06-19T04:48:00Z'` \
  --header 'apikey: <your-api-key>'

Response Data​

The response data will be returned in JSON format (either the default standard JSON format or the CF-JSON format).

Missing or Invalid Sensor Data​

Physical weather stations, runway sensors, and road sensors can experience temporary transmission outages or sensor malfunctions.

  • In standard JSON responses (format=json), missing values are returned as string literals "//" or "///" (e.g., "airtemp_01mnavg": "//"). Client applications parsing these fields as floats or integers must handle these string placeholders to prevent parsing or type conversion errors.
  • In CF-JSON responses (format=cf-json), missing values are automatically mapped to null (e.g., [null]).

For a detailed description of the observation fields, please refer to the Technical Reference & Schema.

Station Identifiers​

Stations can be identified using either:

  • WMO ID: World Meteorological Organisation numeric identifier (e.g., 93110)
  • ICAO ID: International Civil Aviation Organization alphabetic identifier (e.g., NZKTA)

Data Retention​

  • Retention Period: 60 days from observation time
  • Update Frequency: Every minute
  • Historical Queries: Searches beyond 60 days return no results

Polling strategy​

For real-time applications consuming the 1-Minute Observations API, implementing an optimal polling strategy prevents unnecessary network overhead and ensures you retrieve the latest observations as soon as they are processed.

How ingestion works​

MetService Automatic Weather Stations collect and record observations precisely on the minute. However, it takes approximately 30 to 40 seconds for observations to be transmitted, ingested into our databases, and made available at the API Gateway.

To reliably fetch the latest observation while minimizing API Gateway queries:

  1. Query offset: Poll once every 60 seconds, scheduling your request between 30 and 40 seconds past the minute (e.g., at 13:46:35 to fetch the 13:45:00 observation).
  2. Retry offset: If your query does not return the expected new minute's observation, wait 10 seconds and retry.
  3. Exceptions: Some stations update less frequently. For example, observations for the Lindis Pass station are updated once every 10 minutes.

Ingestion timeline examples​

The table below illustrates the relationship between the client request timestamp and the expected observation timestamp returned by the /latest endpoint:

Request timestamp (UTC)Expected observation timestamp (UTC)Status / Details
13:46:0013:44:00Too early. The 13:45:00 data is still processing.
13:46:1513:44:00Too early. Returns the previous minute's observation.
13:46:3513:45:00Optimal window. Ingestion is complete; returns the latest data.
13:46:4513:45:00Valid window. Returns the 13:45:00 data.
13:47:0013:45:00Transition window. Next minute's ingestion has started.
13:47:3513:46:00Next optimal window. Returns the 13:46:00 data.

Next Steps​

  • FAQ - Common questions and answers

Support​

For technical support or issues with your existing access, please visit our Support & Help Centre.