Common Parameters - Spire Weather API Documentation

Reference for query parameters used across multiple API endpoints.

Location Parameters¶

Parameter	Type	Description	Example
`lat`	number	Latitude in decimal degrees (-90 to 90)	`40.0`
`lon`	number	Longitude in decimal degrees (-180 to 180)	`-105.0`
`location`	string	Named location identifier (ICAO Code, WMO ID, UN/LOCODE)	`icao:KDFW`
`location_id`	string	UUID location identifier	`4ac2ae1f-...`

Location Identifier Formats¶

Format	Description	Example
`icao:{code}`	ICAO airport code	`icao:KJFK`
`wmo:{id}`	WMO synoptic station	`wmo:72259`
`unlocode:{code}`	UN/LOCODE port code	`unlocode:USNYC`

Time Parameters¶

Parameter	Type	Description	Example
`issuance_time`	string	Issuance Time of the forecast run (forecast, optimized point, route, file endpoints)	`2024-01-15T00:00:00Z`
`valid_time_interval`	string	ISO 8601 interval of Valid Time values to return (point, profile, optimized point)	`2024-01-15T00:00:00Z/P1D`
`time`	string	ISO 8601 timestamp or time range (current weather and lightning endpoints only)	`2024-01-15T00:00:00Z`
`start_datetime`, `end_datetime`	string	Time window for tide endpoints	`2024-01-15T00:00:00Z`
`start_date`, `end_date`	string	Date window for soil moisture endpoints	`2024-01-15`

Time Format Examples¶

Single timestamp:

2024-01-15T12:00:00Z

Time range (start/end):

2024-01-15T00:00:00Z/2024-01-16T00:00:00Z

Time range (start + duration):

2024-01-15T00:00:00Z/P7D

Duration Format (ISO 8601)¶

Duration	Description
`PT1H`	1 hour
`PT6H`	6 hours
`P1D`	1 day
`P7D`	7 days
`P1M`	1 month

Data Selection Parameters¶

Parameter	Type	Description	Example
`bundles`	string	Comma-separated Bundle names	`basic,maritime`
`regions`	string	Comma-separated region codes (file endpoints)	`global,europe`
`product`	string	Forecast product (file and status endpoints; default `sof-d`)	`srfs`
`time_bundle`	string	Time Bundle option	`hourly`

Available Bundles¶

Bundle names for the global forecast (sof-d):

basic, clouds, precipitation, thunderstorm, maritime, maritime-atmos, maritime-wave, maritime-wave-ext, agricultural, wind-energy, solar-energy, upper-air, aviation, plus the opt-in basic-accumulation, precipitation-accumulation and solar-energy-accumulation.

Other products use their own bundle names: core-v2, upper-air, thunderstorm, derived (SRFS; core is legacy); core, upper-air, derived (SAIFS-WX); surface, upper-air, derived, derived-upper-air, probabilities, percentiles, each with a :daily or :weekly suffix (SAIFS-S2S). The optimized point endpoint accepts basic, wind-energy and solar-energy.

A bundle outside your subscription returns HTTP 403 with the list of names your key may use. See Data Bundles & Variables for the fields in every bundle.

Available Products¶

Product	Description
`sof-d`	Spire global deterministic forecast (default)
`srfs`	Spire Regional Forecast System (3 km)
`saifs-wx`	Spire AI weather forecast
`saifs-s2s`	Spire AI subseasonal-to-seasonal forecast
`saifs-s2s-regimes`	Weather regime probabilities (CSV) from the S2S forecast
`saifs-wx-regimes`	Weather regime probabilities (CSV) from the AI weather forecast

Current weather conditions (cwc) are served by the /current/weather endpoints rather than through product=.

Available Regions¶

Regions vary by subscription. Global forecast regions:

Region	Coverage
`global`	Worldwide
`africa`	Africa
`asia`	Asia
`atlantic`	Atlantic Ocean
`conus`	Contiguous United States
`europe`	Europe
`north-america_central-america_caribbean`	North America, Central America, Caribbean
`south-america`	South America
`south-west_pacific`	South-West Pacific

Regional products cover a subset (SRFS: conus, europe). Use the codes exactly as written. See the Operational Reference.

Output Format Parameters¶

Parameter	Type	Description	Example
`unit_system`	string	Unit system for response	`si`, `us` or `us-f`
`tz`	string	Timezone for timestamps	`America/New_York`

Unit Systems¶

System	Description
`si`	SI Units (default): K, Pa, m/s, m, mm
`us`	US Units with Celsius: °C, hPa, mph, miles, inches
`us-f`	US Units with Fahrenheit: °F, hPa, mph, miles, inches

See Units Reference for complete unit mappings.

Timezone Format¶

Use standard IANA timezone identifiers, or local to use the time zone of the requested coordinates:

UTC (default)
America/New_York
Europe/London
Asia/Tokyo
local

Filtering Parameters¶

Parameter	Type	Description
`prefix`	string	Filter files starting with value
`suffix`	string	Filter files ending with value
`contains`	string	Filter files containing value

Pagination Parameters¶

Parameter	Type	Default	Description
`limit`	integer	100	Maximum items to return
`offset`	integer	0	Number of items to skip

Pagination applies to the Storm Tracks endpoints. Other list endpoints return the complete list.

Request Headers¶

Header	Description	Example
`spire-api-key`	API authentication key	`your-api-key`
`X-Fields`	Field Mask for response filtering	`{data{values{air_temperature}}}`
`Content-Type`	Request body format	`application/json`

Field Mask Syntax¶

Use X-Fields header to request specific fields:

# Only return temperature and wind speed
-H 'X-Fields: {data{values{air_temperature,wind_speed}}}'

On /forecast/point and /forecast/latest/point the mask may only select keys inside data{values{...}}; location, times and meta are always returned. The optimized point, current weather and route endpoints also accept masks such as {data{times,values{air_temperature}}}.

Example: Complete Request¶

curl -X GET \
  'https://api.wx.spire.com/forecast/point?lat=40.0&lon=-105.0&bundles=basic,maritime&unit_system=si&issuance_time=2024-01-15T00:00:00Z&valid_time_interval=2024-01-15T00:00:00Z/P7D&time_bundle=6_hourly' \
  -H 'spire-api-key: YOUR_API_KEY' \
  -H 'X-Fields: {data{values{air_temperature,wind_speed,sea_surface_wave_significant_height}}}'