Travel and placesWeather forecast · Open-Meteo

weather.forecast

Returns current conditions and a daily forecast for a place name or coordinates. Optional include adds current air quality with its timestamp and units, or daily marine (waves) data. Air quality is a current snapshot, not a forecast. One record per call.

POST/v1/capabilities/weather.forecast/execute
Charge returned per callStable
operationId
executeWeatherForecast
Source
Open-Meteo
Typical credits
0 (free source)
Search deadline
15 s server-side
Paging
single result
Availability
ConfiguredChecked 2026-11-20 03:29 UTC
Cost basis
Free. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request body

Body of POST /v1/capabilities/weather.forecast/execute, JSON, validated against the WeatherForecastRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of weather.forecast
FieldDescription
locationstring | objectREQUIRED—
location.latnumberREQUIREDwhen option 2min -90 · max 90
location.lonnumberREQUIREDwhen option 2min -180 · max 180
daysintegerDefault 3.min 1 · max 16
units"metric" | "imperial"Default "metric".
include"air_quality" | "marine"[]max items 2 · unique items
  • Unknown keys are rejected with 400 invalid_request.

Examples

City
curl
curl -s -X POST https://api.powerups-ai.store/v1/capabilities/weather.forecast/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"location":"London","days":3}'
Coordinates, imperial, with air quality
curl
curl -s -X POST https://api.powerups-ai.store/v1/capabilities/weather.forecast/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"location":{"lat":40.71,"lon":-74},"units":"imperial","include":["air_quality"]}'

Record fields

Each item in results[] carries record_id and title (contract, always present) and usually url and snippet. The other keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the WeatherForecastRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. Anything else comes from the provider and may change; see stability tiers.

Record keys of weather.forecast
KeyNote
record_idstringALWAYSUse it with record actions on POST /v1/follow-up.
titlestringALWAYSContract key.
urlstringContract key; usually present.
snippetstringContract key; usually present.
attributionstringALWAYSOn every record.
source_urlstringALWAYSOn every record.
licensestringALWAYSOn every record.
license_urlstringALWAYSOn every record.
locationobjectALWAYSname, lat, lon, timezone, elevation_m.
unitsobjectALWAYStemperature, wind, precipitation unit labels.
currentobjectALWAYSOn every record.
dailyobject[]ALWAYSOne entry per requested day.
air_qualityobjectOnly with include: ["air_quality"].
marineobject[]Only with include: ["marine"] near a coast.

Attribution emitted with every record: Weather data by Open-Meteo (CC BY 4.0).

Follow-ups

Paging: Single result; more is refused with 400 invalid_request.

Not offered: update and record actions.

Detail behaviour: No record actions.

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)
const { data, error } = await client.POST("/v1/capabilities/weather.forecast/execute", {
  body: {
    "location": "London",
    "days": 3
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);
Recorded responseproduction · 26 Sep
Request
POST /v1/capabilities/weather.forecast/execute

{
  "location": "London",
  "days": 3
}