Archive Data - Spire Weather API Documentation

Access historical weather data through Archive Data retrieval requests. Historical data is available dating back to January 1, 1990.

Overview¶

Archive data retrieval is an asynchronous process:

Submit an archive request
Check job status (job progresses through several stages)
Download files when ready

Endpoints¶

Method	Endpoint	Description
POST	`/archive/route`	Request archive data along a route
GET	`/archive/jobs/{job_uuid}/status`	Check archive job status
GET	`/archive/availability`	Check data availability
GET	`/export/{request_id}`	List files from archive request
GET	`/export/{request_id}/{file_id}`	Download archive file

Archive Route Request¶

POST /archive/route

Request historical weather data along a route with timestamps.

Request Body¶

The request body uses the same route structure as the forecast route endpoint, with additional options for variable selection and output format:

{
  "route": {
    "name": "historical_voyage",
    "waypoints": [
      {
        "lat": 40.0,
        "lon": -74.0,
        "time": "2023-06-15T12:00:00Z"
      },
      {
        "lat": 41.0,
        "lon": -70.0,
        "time": "2023-06-15T18:00:00Z"
      },
      {
        "lat": 42.0,
        "lon": -66.0,
        "time": "2023-06-16T00:00:00Z"
      }
    ]
  },
  "variables": [
    "air_temperature",
    "wind_speed",
    "wind_direction",
    "significant_wave_height"
  ],
  "output_format": "csv"
}

Request Body Fields¶

Field	Type	Required	Description
`route`	object	Yes	Route definition
`route.name`	string	Yes	Name for the route
`route.waypoints`	array	Yes	Array of waypoints (max 120)
`route.waypoints[].lat`	number	Yes	Latitude
`route.waypoints[].lon`	number	Yes	Longitude
`route.waypoints[].time`	string	Yes	ISO 8601 timestamp
`variables`	array	No	Specific variables to include (default: all available)
`output_format`	string	No	Output file format (`csv`, `json`)

Example Request¶

Shell

Python

Node.js

curl -X POST \
  'https://api.wx.spire.com/archive/route' \
  -H 'spire-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "route": {
      "name": "historical_voyage",
      "waypoints": [
        {"lat": 40.0, "lon": -74.0, "time": "2023-06-15T12:00:00Z"},
        {"lat": 42.0, "lon": -66.0, "time": "2023-06-16T00:00:00Z"}
      ]
    },
    "variables": ["air_temperature", "wind_speed", "significant_wave_height"],
    "output_format": "csv"
  }'

import requests

response = requests.post(
    "https://api.wx.spire.com/archive/route",
    headers={"spire-api-key": "YOUR_API_KEY"},
    json={
        "route": {
            "name": "historical_voyage",
            "waypoints": [
                {"lat": 40.0, "lon": -74.0, "time": "2023-06-15T12:00:00Z"},
                {"lat": 42.0, "lon": -66.0, "time": "2023-06-16T00:00:00Z"},
            ],
        },
        "variables": ["air_temperature", "wind_speed", "significant_wave_height"],
        "output_format": "csv",
    },
)
data = response.json()

const response = await fetch("https://api.wx.spire.com/archive/route", {
  method: "POST",
  headers: {
    "spire-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    route: {
      name: "historical_voyage",
      waypoints: [
        { lat: 40.0, lon: -74.0, time: "2023-06-15T12:00:00Z" },
        { lat: 42.0, lon: -66.0, time: "2023-06-16T00:00:00Z" },
      ],
    },
    variables: ["air_temperature", "wind_speed", "significant_wave_height"],
    output_format: "csv",
  }),
});
const data = await response.json();

Response¶

{
  "job_uuid": "abc123-def456-789xyz",
  "status": "CREATED"
}

Check Job Status¶

GET /archive/jobs/{job_uuid}/status

Check the status of an archive data retrieval job.

Path Parameters¶

Parameter	Type	Required	Description
`job_uuid`	string	Yes	Job identifier from request

Example Request¶

Shell

Python

Node.js

curl -X GET \
  'https://api.wx.spire.com/archive/jobs/abc123-def456-789xyz/status' \
  -H 'spire-api-key: YOUR_API_KEY'

Response¶

{
  "job_uuid": "abc123-def456-789xyz",
  "status": "COMPLETED",
  "request_id": "oe4ticpccVx9uyM9T33x6jf"
}

Status Values¶

Archive jobs progress through multiple stages:

Status	Description
`CREATED`	Job submitted, queued for processing
`RESTORING_FILES`	Retrieving archived data from storage
`RESTORE_COMPLETED`	Archived data retrieved, ready for extraction
`INITIATED`	Extraction process initiated
`PROCESSING`	Data extraction in progress
`COMPLETED`	Data ready for download
`FAILED`	Job failed
`UNKNOWN`	Status could not be determined

Check Data Availability¶

GET /archive/availability

Check what historical data is available for a given time range and location.

List Export Files¶

GET /export/{request_id}

Retrieve a list of files available from a completed archive request.

Path Parameters¶

Parameter	Type	Required	Description
`request_id`	string	Yes	Request identifier from completed job

Example Request¶

Shell

Python

Node.js

curl -X GET \
  'https://api.wx.spire.com/export/oe4ticpccVx9uyM9T33x6jf' \
  -H 'spire-api-key: YOUR_API_KEY'

Response¶

{
  "meta": {
    "count": 2
  },
  "files": [
    "archive_route_2023-06-15.csv",
    "archive_route_2023-06-16.csv"
  ]
}

Download Export File¶

GET /export/{request_id}/{file_id}

Download a specific file from an archive export.

Path Parameters¶

Parameter	Type	Required	Description
`request_id`	string	Yes	Request identifier
`file_id`	string	Yes	Filename to download

Example Request¶

Shell

Python

Node.js

curl -OJL -X GET \
  'https://api.wx.spire.com/export/oe4ticpccVx9uyM9T33x6jf/archive_route_2023-06-15.csv' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/export/oe4ticpccVx9uyM9T33x6jf/archive_route_2023-06-15.csv",
    headers={"spire-api-key": "YOUR_API_KEY"},
    allow_redirects=True,
)

with open("archive_route_2023-06-15.csv", "wb") as f:
    f.write(response.content)

import { createWriteStream } from "fs";
import { Readable } from "stream";

const response = await fetch(
  "https://api.wx.spire.com/export/oe4ticpccVx9uyM9T33x6jf/archive_route_2023-06-15.csv",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);

const fileStream = createWriteStream("archive_route_2023-06-15.csv");
Readable.fromWeb(response.body).pipe(fileStream);

Python Example¶

Complete workflow for archive data retrieval:

import requests
import time

headers = {'spire-api-key': 'YOUR_API_KEY'}
base_url = 'https://api.wx.spire.com'

# 1. Submit archive request
route_data = {
    "route": {
        "name": "historical_voyage",
        "waypoints": [
            {"lat": 40.0, "lon": -74.0, "time": "2023-06-15T12:00:00Z"},
            {"lat": 41.0, "lon": -70.0, "time": "2023-06-15T18:00:00Z"},
            {"lat": 42.0, "lon": -66.0, "time": "2023-06-16T00:00:00Z"}
        ]
    },
    "variables": [
        "air_temperature",
        "wind_speed",
        "wind_direction",
        "significant_wave_height"
    ],
    "output_format": "csv"
}

response = requests.post(
    f'{base_url}/archive/route',
    headers=headers,
    json=route_data
)
job = response.json()
job_uuid = job['job_uuid']
print(f"Job submitted: {job_uuid}")

# 2. Poll for completion
terminal_statuses = {'COMPLETED', 'FAILED', 'UNKNOWN'}
while True:
    status_response = requests.get(
        f'{base_url}/archive/jobs/{job_uuid}/status',
        headers=headers
    )
    status = status_response.json()
    print(f"Status: {status['status']}")

    if status['status'] in terminal_statuses:
        break

    time.sleep(30)  # Wait before checking again

if status['status'] != 'COMPLETED':
    raise Exception(f"Archive job ended with status: {status['status']}")

request_id = status['request_id']

# 3. List and download files
files_response = requests.get(
    f'{base_url}/export/{request_id}',
    headers=headers
)
files = files_response.json()['files']

for filename in files:
    file_response = requests.get(
        f'{base_url}/export/{request_id}/{filename}',
        headers=headers,
        allow_redirects=True
    )
    with open(filename, 'wb') as f:
        f.write(file_response.content)
    print(f'Downloaded: {filename}')