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
`time`	string	ISO 8601 timestamp or time range	`2024-01-15T00:00:00Z`
`issuance`	string	Issuance Time	`2024-01-15T00:00:00Z`
`valid_time`	string	Valid Time or interval	`2024-01-15T00:00:00Z/P1D`

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 names	`global,north_america`
`product`	string	Product identifier	`sof`
`time_bundle`	string	Time Bundle option	`hourly`

Available Bundles¶

Bundle	Description
`basic`	Standard meteorological variables
`maritime`	Marine-specific parameters
`agricultural`	Agriculture-focused variables
`aviation`	Aviation weather parameters
`solar`	Solar radiation data
`wind`	Wind power parameters
`precipitation`	Detailed precipitation data

Available Regions¶

Regions vary by subscription. Common options:

Region	Coverage
`global`	Worldwide
`north_america`	North America
`europe`	Europe
`asia`	Asia
`australia`	Australia

Output Format Parameters¶

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

Unit Systems¶

System	Description
`si`	SI Units (default)
`us`	US Units

See Units Reference for complete unit mappings.

Timezone Format¶

Use standard IANA timezone identifiers:

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

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

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}}}'

# Return location and temperature only
-H 'X-Fields: {data{location,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=2024-01-15T00:00:00Z&valid_time=2024-01-15T00:00:00Z/P7D' \
  -H 'spire-api-key: YOUR_API_KEY' \
  -H 'X-Fields: {meta,data{times,values{air_temperature,wind_speed,significant_wave_height}}}'