API Specification

Complete technical specification for the 1-Minute Observations API endpoints, parameters, and responses.

Base Information

• Title: 1 Minute Observations API
• Version: 4.3.2
• Base URI: https://api.metservice.com/observations/nz/1-minute
• Protocol: HTTPS
• Media Type: application/json

Endpoints

1. List Weather Stations

Endpoint: GET /weatherStation

Description: Returns a list of weather station, runway or road sensor identifiers and known metadata for which at least 1 observation has been received in the last 60 minutes.

Headers:

apikey: l7324423gfsdg534534543fsdf

Response Codes:

• 200 - Success: The list of station and sensor identifiers with metadata
• 400 - Bad Request: Malformed request or incorrect parameters
• 401 - Unauthorized: Invalid or missing API key
• 500 - Internal Server Error: Unexpected server error

Example Request:

curl -X GET "https://api.metservice.com/observations/nz/1-minute/weatherStation" \
  -H "apikey: your-api-key-here"

---

2. Get Latest Observation

Endpoint: GET /weatherStation/{stationId}/latest

Description: Get the latest observation for a weather station or sensor.

URI Parameters:

Parameter	Type	Required	Description	Example
stationId	string	Yes	The numeric WMO or alpha-numeric ICAO identifier for this weather station or sensor. Length: 5 characters	93110

Query Parameters:

Parameter	Type	Required	Default	Description	Example
format	string	No	json	The format of the returned JSON payload	json, cf-json
vars	string	No	-	Comma-separated list of observed variable names to return	prwxst1_15mnavg,relhumd_01hrmin,wndgstm_01hrdir

Headers:

apikey: l7324423gfsdg534534543fsdf

Response Codes:

• 200 - Success: The last received observed data for the specified station
• 400 - Bad Request: Invalid station ID or parameters
• 401 - Unauthorized: Invalid API key or insufficient permissions
• 500 - Internal Server Error: Unexpected server error

Example Request:

curl -X GET "https://api.metservice.com/observations/nz/1-minute/weatherStation/93110/latest?format=json&vars=airtemp_01mnavg,windspd_01mnavg" \
  -H "apikey: your-api-key-here"

---

3. Get Last N Minutes of Data

Endpoint: GET /weatherStation/{stationId}/last/{minutes}/minutes

Description: Get the last n minutes of observation data for a weather station or sensor.

URI Parameters:

Parameter	Type	Required	Description	Constraints	Example
stationId	string	Yes	The numeric WMO or alpha-numeric ICAO identifier	Length: 5 characters	93110
minutes	number	Yes	Number of minutes of observations to return going back from current time	Min: 1, Max: 1440	60

Query Parameters:

Parameter	Type	Required	Default	Description	Constraints
format	string	No	json	The format of the returned JSON payload	json, cf-json
vars	string	No	-	Comma-separated list of observed variable names	-

Format Constraints:

• JSON format: 1-1440 minutes allowed
• CF-JSON format: 1-360 minutes allowed

Headers:

apikey: l7324423gfsdg534534543fsdf

Response Codes:

• 200 - Success: The last n minutes of observed data
• 400 - Bad Request: Invalid parameters or time range
• 401 - Unauthorized: Invalid API key
• 500 - Internal Server Error: Unexpected server error

Example Request:

curl -X GET "https://api.metservice.com/observations/nz/1-minute/weatherStation/NZKTA/last/10/minutes?format=cf-json" \
  -H "apikey: your-api-key-here"

---

4. Get Data by Date Range

Endpoint: GET /weatherStation/{stationId}/range/{fromDateTime}/{toDateTime}

Description: Get observation data for a specified date time range.

URI Parameters:

Parameter	Type	Required	Description	Format	Example
stationId	string	Yes	The numeric WMO or alpha-numeric ICAO identifier	Length: 5 characters	NZNUX
fromDateTime	datetime	Yes	Start date/time of the range	RFC-3339	2020-06-10T02:55:00Z
toDateTime	datetime	Yes	End date/time of the range	RFC-3339	2020-06-10T02:56:00Z

Query Parameters:

Parameter	Type	Required	Default	Description
format	string	No	json	The format of the returned JSON payload
vars	string	No	-	Comma-separated list of observed variable names

Time Range Constraints:

• JSON format: 1-1440 minutes between fromDateTime and toDateTime
• CF-JSON format: 1-360 minutes between fromDateTime and toDateTime
• Data retention: Maximum 60 days from current time

Headers:

apikey: l7324423gfsdg534534543fsdf

Response Codes:

• 200 - Success: Observed data for the specified time range
• 400 - Bad Request: Invalid date format or time range
• 401 - Unauthorized: Invalid API key
• 500 - Internal Server Error: Unexpected server error

Example Request:

curl -X GET "https://api.metservice.com/observations/nz/1-minute/weatherStation/93110/range/2020-06-19T04:00:00Z/2020-06-19T04:48:00Z" \
  -H "apikey: your-api-key-here"

Authentication Methods

API Key Authentication

Include the API key in the request header:

apikey: your-api-key-here

Bearer Token Authentication

Include the bearer token in the Authorization header:

Authorization: Bearer your-bearer-token-here

Response Format

All successful responses follow this structure:

{
  "version": "1.0",
  "request-time": "2021-10-05T23:00:43Z",
  "path": "/observations/nz/1-minute/weatherStation",
  "attributes": {
    "dataset": "observation:1minuteobservation",
    "provider": "metservice"
  },
  "results": [
    // Array of observation data or station metadata
  ]
}

Response Fields

Field	Type	Description
version	string	API version
request-time	string	ISO 8601 timestamp when request was processed
path	string	The requested endpoint path
attributes	object	Metadata about the dataset and request
results	array	Array containing the requested data

Error Responses

Error responses include detailed information:

{
  "version": "1.0",
  "request-time": "2021-10-05T23:00:43Z",
  "path": "/observations/nz/1-minute/weatherStation/invalid",
  "error": {
    "code": 400,
    "message": "Invalid station identifier",
    "details": "Station ID must be 5 characters (WMO or ICAO format)"
  }
}

Data Types and Formats

Station Identifiers

• WMO ID: 5-digit numeric identifier (e.g., 93110)
• ICAO ID: 5-character alphanumeric identifier (e.g., NZKTA)

Date/Time Format

• Format: RFC-3339 (ISO 8601)
• Timezone: UTC
• Example: 2020-06-19T04:00:00Z

Variable Names

Common observation variables include:

• airtemp_01mnavg - Air temperature (1-minute average)
• windspd_01mnavg - Wind speed (1-minute average)
• rainfal_01mnacc - Rainfall (1-minute accumulation)
• relhumd_01hrmin - Relative humidity (1-hour minimum)
• obs_timestamp - Observation timestamp (always included)

Rate Limits

Rate limits vary by API account plan:

• Requests per second limits
• Daily request quotas
• Concurrent connection limits

Exceeding limits results in 429 Too Many Requests responses.

Best Practices

1. Caching: Cache station metadata from /weatherStation endpoint
2. Error Handling: Implement retry logic with exponential backoff
3. Variable Filtering: Use vars parameter to reduce response size
4. Time Ranges: Keep time ranges within format constraints
5. Authentication: Securely store and rotate API keys
6. Monitoring: Monitor response times and error rates