Travel and places · 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.

Operation: POST /v1/capabilities/weather.forecast/execute
operationId: executeWeatherForecast
Typical credits: 0
Search deadline: 15 s server-side
Paging: single result
Availability: ConfiguredChecked 2026-09-23 21:02 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 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
Field	Type	Required	Default	Constraints and description
location	string \| object	yes
location.latwhen option 2	number	yes		min -90, max 90
location.lonwhen option 2	number	yes		min -180, max 180
days	integer	no	3	min 1, max 16
units	"metric" \| "imperial"	no	"metric"
include	"air_quality" \| "marine"[]	no		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"]}'

Recorded response

Captured from the production API on 2026-09-20 (release f80cd03e) for the request below. Long arrays are abridged here; values change with the source.

request

{
  "location": {
    "lat": 38.7223,
    "lon": -9.1393
  },
  "days": 16,
  "include": [
    "air_quality",
    "marine"
  ]
}

response (abridged)

{
  "search_id": "srch_ePaazJiKYqmgc0hK",
  "capability": "weather.forecast",
  "results": [
    {
      "record_id": "rec_siQNelpEPOWay4PB",
      "title": "Forecast for 38.7223, -9.1393",
      "attribution": "Weather data by Open-Meteo",
      "source_url": "https://open-meteo.com/",
      "license": "CC BY 4.0",
      "license_url": "https://creativecommons.org/licenses/by/4.0/",
      "location": {
        "name": "38.7223, -9.1393",
        "lat": 38.7223,
        "lon": -9.1393,
        "timezone": "Europe/Lisbon",
        "elevation_m": 66
      },
      "units": {
        "temperature": "°C",
        "wind": "km/h",
        "precipitation": "mm"
      },
      "current": {
        "time": "2026-09-20T10:15",
        "conditions": "clear sky",
        "temperature": 23.2,
        "feels_like": 22.7,
        "humidity": 47,
        "wind": 5.9,
        "precipitation": 0
      },
      "daily": [
        {
          "date": "2026-09-20",
          "conditions": "mainly clear",
          "high": 31.7,
          "low": 20.7,
          "precipitation": 0,
          "precipitation_chance": 0,
          "wind_max": 14.5,
          "uv_index_max": 6.45,
          "sunrise": "2026-09-20T07:22",
          "sunset": "2026-09-20T19:36"
        },
        {
          "date": "2026-09-21",
          "conditions": "overcast",
          "high": 32.8,
          "low": 19.6,
          "precipitation": 0,
          "precipitation_chance": 0,
          "wind_max": 16.1,
          "uv_index_max": 6.4,
          "sunrise": "2026-09-21T07:23",
          "sunset": "2026-09-21T19:35"
        },
        "… 14 more"
      ],
      "air_quality": {
        "type": "current",
        "time": "2026-09-20T10:00",
        "timezone": "Europe/Lisbon",
        "utc_offset_seconds": 3600,
        "interval_seconds": 3600,
        "attribution": "Copernicus Atmosphere Monitoring Service (CAMS), via Open-Meteo",
        "source_url": "https://open-meteo.com/en/docs/air-quality-api",
        "data_source_url": "https://ads.atmosphere.copernicus.eu/",
        "units": {
          "european_aqi": "EAQI",
          "us_aqi": "USAQI",
          "pm2_5": "μg/m³",
          "pm10": "μg/m³",
          "ozone": "μg/m³"
        },
        "european_aqi": 32,
        "us_aqi": 52,
        "pm2_5": 10.2,
        "pm10": 14.2,
        "ozone": 44
      },
      "marine": [
        {
          "date": "2026-09-20",
          "wave_height_max_m": 0.64,
          "wave_direction": 317,
          "wave_period_max_s": 9.7
        },
        {
          "date": "2026-09-21",
          "wave_height_max_m": 0.58,
          "wave_direction": 312,
          "wave_period_max_s": 10.5
        },
        "… 14 more"
      ]
    }
  ],
  "result_count": 1,
  "has_more": false,
  "next": {
    "url": "/v1/follow-up",
    "actions": [],
    "example": {
      "search_id": "srch_ePaazJiKYqmgc0hK",
      "action": "more"
    }
  },
  "record_actions": [],
  "charged_credits": 0,
  "balance": {
    "used": 91,
    "cap": 15000,
    "period_end": "2026-10-19T17:35:40.303Z"
  }
}

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The 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. See stability tiers.

Record keys of weather.forecast
Key	Type	Presence	Note
attribution	string	always
source_url	string	always
license	string	always
license_url	string	always
location	object	always	`name`, `lat`, `lon`, `timezone`, `elevation_m`.
units	object	always	`temperature`, `wind`, `precipitation` unit labels.
current	object	always
daily	object[]	always	One entry per requested day.
air_quality	object	when the source has it	Only with `include: ["air_quality"]`.
marine	object[]	when the source has it	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.
Update: not offered.
Record actions: none.
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);