API Reference

Weather API Reference

Base URL

https://weather.maptoolkit.net

Endpoints

`GET /forecast/{model}`

Point forecast

Returns the weather forecast for a specific coordinate, starting from the current time.

Parameter	In	Type	Required	Description
`model`	path	string	Yes	Weather model identifier.
`lat`	query	number	Yes	Latitude of the forecast location.
`lng`	query	number	Yes	Longitude of the forecast location.
`forecast`	query	integer	No	Number of hours to forecast. Returns only the current weather when omitted. Default: 0.

Status Description

200 Forecast returned successfully.

Status	Description
`200`	Forecast returned successfully.
`500`	No weather data available or an error occurred. Possible messages: Model errors: `unknown weathermodel` — The `{model}` path parameter does not match a known model Data errors: `no weatherdata found` — No weather table exists for the requested time and model `no weather data` — Tile could not be generated due to missing data Parameter errors: `lng and lat HTTP parameters missing` — The `lat` or `lng` query parameter is missing or not a valid number

500

No weather data available or an error occurred. Possible messages:

Model errors:

unknown weathermodel — The {model} path parameter does not match a known model

Data errors:

no weatherdata found — No weather table exists for the requested time and model
no weather data — Tile could not be generated due to missing data

Parameter errors:

lng and lat HTTP parameters missing — The lat or lng query parameter is missing or not a valid number

`GET /raster/{model}.{forecast}.json`

Raster tile source descriptor

Returns a TileJSON descriptor for the weather raster tile source at the given forecast offset.

Parameter	In	Type	Required	Description
`model`	path	string	Yes	Weather model identifier.
`forecast`	path	integer	Yes	Forecast offset in hours from the current time. `0` is the current weather.

Status Description

200 TileJSON descriptor returned successfully.

Status	Description
`200`	TileJSON descriptor returned successfully.
`500`	No weather data available or an error occurred. Possible messages: Model errors: `unknown weathermodel` — The `{model}` path parameter does not match a known model Data errors: `no weatherdata found` — No weather table exists for the requested time and model `no weather data` — Tile could not be generated due to missing data Parameter errors: `lng and lat HTTP parameters missing` — The `lat` or `lng` query parameter is missing or not a valid number

500

No weather data available or an error occurred. Possible messages:

Model errors:

unknown weathermodel — The {model} path parameter does not match a known model

Data errors:

no weatherdata found — No weather table exists for the requested time and model
no weather data — Tile could not be generated due to missing data

Parameter errors:

lng and lat HTTP parameters missing — The lat or lng query parameter is missing or not a valid number

`GET /raster/{model}/{z}/{x}/{y}.{forecast}.png`

Raster tile

Returns an RGB-encoded raster tile where each pixel encodes weather data in its RGBA channels. This is an internal encoding format used by the server; use the vector tiles or the forecast endpoint for human-readable data.

Parameter	In	Type	Required	Description
`model`	path	string	Yes	Weather model identifier.
`forecast`	path	integer	Yes	Forecast offset in hours from the current time. `0` is the current weather.
`z`	path	integer	Yes	Tile zoom level.
`x`	path	integer	Yes	Tile column index.
`y`	path	integer	Yes	Tile row index.

Status Description

200 Raster tile returned successfully.

Status	Description
`200`	Raster tile returned successfully.
`404`	No weather data available or an error occurred. Possible messages: Model errors: `unknown weathermodel` — The `{model}` path parameter does not match a known model Data errors: `no weatherdata found` — No weather table exists for the requested time and model `no weather data` — Tile could not be generated due to missing data Parameter errors: `lng and lat HTTP parameters missing` — The `lat` or `lng` query parameter is missing or not a valid number
`500`	An unexpected server error occurred.

404

No weather data available or an error occurred. Possible messages:

Model errors:

unknown weathermodel — The {model} path parameter does not match a known model

Data errors:

no weatherdata found — No weather table exists for the requested time and model
no weather data — Tile could not be generated due to missing data

Parameter errors:

lng and lat HTTP parameters missing — The lat or lng query parameter is missing or not a valid number

500 An unexpected server error occurred.

`GET /vector/{model}.{forecast}.json`

Vector tile source descriptor

Returns a TileJSON descriptor for the weather vector tile source at the given forecast offset.

Parameter	In	Type	Required	Description
`model`	path	string	Yes	Weather model identifier.
`forecast`	path	integer	Yes	Forecast offset in hours from the current time. `0` is the current weather.

Status Description

200 TileJSON descriptor returned successfully.

Status	Description
`200`	TileJSON descriptor returned successfully.
`500`	No weather data available or an error occurred. Possible messages: Model errors: `unknown weathermodel` — The `{model}` path parameter does not match a known model Data errors: `no weatherdata found` — No weather table exists for the requested time and model `no weather data` — Tile could not be generated due to missing data Parameter errors: `lng and lat HTTP parameters missing` — The `lat` or `lng` query parameter is missing or not a valid number

500

No weather data available or an error occurred. Possible messages:

Model errors:

unknown weathermodel — The {model} path parameter does not match a known model

Data errors:

no weatherdata found — No weather table exists for the requested time and model
no weather data — Tile could not be generated due to missing data

Parameter errors:

lng and lat HTTP parameters missing — The lat or lng query parameter is missing or not a valid number

`GET /vector/{model}/{z}/{x}/{y}.{forecast}.pbf`

Vector tile

Returns a Mapbox Vector Tile (PBF) for the given tile coordinates and forecast offset.

The tile contains the following layers:

Layer	Field	Description
`temperature`	`degree`	Temperature in °C
`precipitation`	`mm`	Precipitation in mm/h
`wind`	`ms`	Wind speed in m/s
`weather`	`code`	Weather condition code
`weather_label`	multiple	Grid of weather data points with full forecast values
`place_label`	multiple	Place names enriched with current weather data

Parameter	In	Type	Required	Description
`model`	path	string	Yes	Weather model identifier.
`forecast`	path	integer	Yes	Forecast offset in hours from the current time. `0` is the current weather.
`z`	path	integer	Yes	Tile zoom level.
`x`	path	integer	Yes	Tile column index.
`y`	path	integer	Yes	Tile row index.

Status Description

200 Vector tile returned successfully.

Status	Description
`200`	Vector tile returned successfully.
`404`	No weather data available or an error occurred. Possible messages: Model errors: `unknown weathermodel` — The `{model}` path parameter does not match a known model Data errors: `no weatherdata found` — No weather table exists for the requested time and model `no weather data` — Tile could not be generated due to missing data Parameter errors: `lng and lat HTTP parameters missing` — The `lat` or `lng` query parameter is missing or not a valid number
`500`	An unexpected server error occurred.

404

No weather data available or an error occurred. Possible messages:

Model errors:

unknown weathermodel — The {model} path parameter does not match a known model

Data errors:

no weatherdata found — No weather table exists for the requested time and model
no weather data — Tile could not be generated due to missing data

Parameter errors:

lng and lat HTTP parameters missing — The lat or lng query parameter is missing or not a valid number

500 An unexpected server error occurred.

Try it

The console below sends live requests against the endpoints above. You can browse it without an API key; Execute needs one, because every endpoint requires the api_key query parameter and returns 403 without it. Use Authorize to add your key. See First Steps if you do not have one yet.