Docs

Every endpoint is a GET with query parameters, except batch and webhooks. Responses are JSON. The base URL is https://api.breezeweather.com; the same reference, interactive, lives at https://api.breezeweather.com/docs.

Authentication

Send your key as X-API-Key or Authorization: Bearer. Keys never go in the query string.

curl "https://api.breezeweather.com/current?lat=40.7128&lon=-74.006" -H "X-API-Key: bw_..."

Locations

Pass lat and lon, a locationId from an earlier response, or a place name with location= or city=&state=&country=. US points come from the National Weather Service, Canadian points from Environment Canada, and everywhere else from MET Norway. History comes from NOAA NCEI stations worldwide, Environment Canada's climate archive in Canada, and Open-Meteo's ERA5 reanalysis where no station is near. Alerts come from the National Weather Service, Environment Canada and, across Europe, Meteoalarm. Every response names its source.

Parameters every weather endpoint accepts

units=metric|imperial|standard|si picks the unit system; every response carries a units object saying what you got. timezone=local returns timestamps in the location's zone. fields= and excludeFields= trim the payload.

Parameter	Type	Default
locationId	string		A locationId from a previous response
lat	number		Latitude
lon	number		Longitude
location	string		Free-text place name, e.g. 'Toronto, ON'
city	string		City name, with state and country
state	string		State or province code
country	string		ISO 3166-1 alpha-2
units	metric \| imperial \| standard \| si	metric	Unit system for measurements
timezone	string	UTC	UTC or the location's local time
fields	string		Comma-separated fields to include
excludeFields	string		Comma-separated fields to omit
lang	string	en	Language for text (only en is available)

Weather

GET/currentCurrent conditions

Response fields

astronomy	AstronomyOut
cloudCover	integer
dewPoint	number
feelsLike	number
humidity	integer
location	LocationInfo
observationTime	date-time
precipitation	number
precipitationProbability	integer
pressure	number
pressureSeaLevel	number
rain	number
snow	number
source	SourceOut
stationId	string
temperature	number
temperatureMax	number
temperatureMin	number
units	Units
uvIndex	number
visibility	number
weatherCode	integer
weatherDescription	string
weatherIcon	string
weatherMain	string
windDirection	number
windDirectionCompass	string
windGust	number
windSpeed	number

GET/forecast/dailyDaily forecast

Parameter	Type	Default
days	integer	7	Days to return, 1 to 14

Response fields

forecast	DailyForecastOut[]
location	LocationInfo
source	SourceOut
units	Units

GET/forecast/hourlyHourly forecast

Parameter	Type	Default
hours	integer	48	Hours to return, 1 to 168

Response fields

forecast	HourlyForecastOut[]
location	LocationInfo
source	SourceOut
units	Units

GET/alerts/activeActive alerts

Parameter	Type	Default
severity	string[]		Keep only these severities: extreme, severe, moderate, minor
urgency	string[]		Keep only these urgencies: immediate, expected, future, past

Response fields

alerts	WeatherAlert[]
location	LocationInfo
source	SourceOut

GET/historical/dailyPast days, aggregated from station observations

Parameter	Type	Default
date*	string		First day, YYYY-MM-DD
endDate	string		YYYY-MM-DD, inclusive
page	integer	1	Page number
pageSize	integer	50	Rows per page

Response fields

data	HistoricalDaily[]
location	LocationInfo
pagination	Pagination
source	SourceOut
units	Units

GET/historical/hourlyPast hourly station observations

Parameter	Type	Default
startDateTime*	string		ISO 8601 date-time
endDateTime*	string		ISO 8601 date-time; at most 7 days after the start
page	integer	1	Page number
pageSize	integer	50	Rows per page

Response fields

data	HistoricalHourly[]
location	LocationInfo
pagination	Pagination
source	SourceOut
units	Units

POST/batchSeveral locations in one call

Response fields

results

BatchResult[]

GET/airqualityAir quality (not offered yet)

GET/forecast/minutelyMinutely precipitation (not offered)

Locations

GET/locations/searchFind places by name

Parameter	Type	Default
q*	string		Place name to search for
limit	integer	10	Maximum results
country	string		Restrict to a country, ISO 3166-1 alpha-2

Response fields

locations

LocationOut[]

GET/locations/geocodeDescribe a coordinate

Parameter	Type	Default
lat*	number		Latitude
lon*	number		Longitude

Response fields

country	string
countryName	string
elevation	number	Metres above sea level
id	string
latitude	number
localName	string
longitude	number
name	string
population	integer
state	string
stateName	string
timezone	string

GET/locations/{location_id}Look up a locationId

Parameter	Type	Default
location_id*	string

Response fields

country	string
countryName	string
elevation	number	Metres above sea level
id	string
latitude	number
localName	string
longitude	number
name	string
population	integer
state	string
stateName	string
timezone	string

Alert webhooks

GET/webhooks/subscriptionsList subscriptions

POST/webhooks/subscriptionsSubscribe to alerts

Response fields

createdAt	date-time
events	string[]
id	string
locations	LocationInfo[]
status	string
thresholds	Thresholds
updatedAt	date-time
url	string

DELETE/webhooks/subscriptions/{subscription_id}Delete a subscription

Parameter	Type	Default
subscription_id*	string

GET/webhooks/subscriptions/{subscription_id}Get a subscription

Parameter	Type	Default
subscription_id*	string

Response fields

createdAt	date-time
events	string[]
id	string
locations	LocationInfo[]
status	string
thresholds	Thresholds
updatedAt	date-time
url	string

Rate limits and errors

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Past the limit you get 429 with Retry-After. Errors always have one shape:

{ "error": { "code": "location_not_found", "message": "no location matched the query", "details": {} } }

code	string
details	Details
message	string

Caching and freshness

Current conditions refresh every 10 minutes, forecasts hourly, alerts every 5 minutes. Responses carry Cache-Control, Last-Modified and ETag; send If-None-Match to get a 304 when nothing changed. If an upstream service fails you get the last good data with source.stale: true. Please credit the source named in each response: NOAA/NWS, Environment and Climate Change Canada, or MET Norway (CC BY 4.0).