---
title: "Daily weather forecast for a coordinate or QWeather location id. Returns a normalized Forecast."
method: POST
path: "/v2/ops/weather.forecast"
tags: ["weather"]
---

# Daily weather forecast for a coordinate or QWeather location id. Returns a normalized Forecast.

`POST /v2/ops/weather.forecast`

## Request

- Base URL: `https://api.agentkey.app`
- URL: `https://api.agentkey.app/v2/ops/weather.forecast`
- Auth: HTTP bearer

3–30 day forecast for a point (lat / lon) or a QWeather LocationID (location_id). City names are not resolved — geocode first. Metric units (°C, mm, km/h); condition / wind texts follow lang (default Chinese).

Fixed price: 0.1 credits per successful call, whichever provider serves it.

## Request body

- object
  - `days` 3 | 7 | 10 | 15 | 30: Forecast length in days (QWeather granularities).
  - `fields` string[]: Projection: keep only these dotted paths of data, e.g. ["items.id", "items.text"].
  - `include_raw` boolean: Attach the raw upstream payload as `raw` (not a stable contract; truncated above 256 KB).
  - `lang` string: BCP 47 language for condition / wind texts, e.g. en, zh-Hans; default is the provider's (Chinese).
  - `lat` number: Latitude in decimal degrees. Required unless location_id is given.
  - `location_id` string: QWeather LocationID (e.g. 101010100 for Beijing) from the QWeather geo API. Give either lat / lon or location_id, not both.
  - `lon` number: Longitude in decimal degrees. Required unless location_id is given.
  - `provider` string: Shorthand for routing.only = [provider].
  - `routing` Routing: Provider routing override. order: try these providers first; only: restrict to these (equivalent to pinning); allow_fallbacks: false tries only the first eligible provider.
    - `allow_fallbacks` boolean: false = try only the first eligible provider.
    - `only` string[]: Restrict to these providers.
    - `order` string[]: Providers to try first, in order.
    - `strategy` 'auto': How eligible providers are ordered. auto = the method's curated order. fastest / stable / popular are specified but not implemented yet (400 until then). The price is fixed whatever the strategy; mutually exclusive with order.

## Response `200`

Success envelope

- ForecastEnvelope: Success envelope whose data is a Forecast.
  - `attempts` Attempt[], required
    - `error_type` string: validation | not_found | rate_limit | timeout | upstream_unauthorized | upstream_unavailable | provider_error
    - `provider` string, required: Provider slug.
    - `refunded` boolean: true when the reservation for this attempt was refunded.
    - `status` integer, required: HTTP status AgentKey mapped this attempt to (200 on success).
    - `took_ms` integer, required
    - `tool` string, required: Registry tool name (Provider/operation) that was called.
    - `upstream_status` integer: The provider's real HTTP status; absent when nothing was received.
  - `credits_charged` number, required: Credits charged for this call (the method's fixed price).
  - `data` object, required: A multi-day weather forecast for one location.
    - `days` object[], required: One entry per forecast day, in date order.
      - `condition` string, nullable, required: Daytime weather condition text in the requested language (Sunny, 多云 …).
      - `date` string, required: Forecast date, YYYY-MM-DD (local date of the location).
      - `humidity` integer, nullable, required: Relative humidity, percent.
      - `precipitation` number, nullable, required: Expected precipitation, mm.
      - `precipitation_probability` integer, nullable, required: Chance of precipitation, percent.
      - `sunrise` string, nullable, required: Sunrise, HH:MM local time.
      - `sunset` string, nullable, required: Sunset, HH:MM local time.
      - `temp_max` number, nullable, required: Maximum temperature, °C.
      - `temp_min` number, nullable, required: Minimum temperature, °C.
      - `wind_direction` string, nullable, required: Daytime wind direction text in the requested language (NE, 东北风 …).
      - `wind_speed` number, nullable, required: Daytime wind speed, km/h.
    - `location` object, required: The forecast location. lat / lon echo the request when the provider does not return them.
      - `lat` number, nullable, required: Latitude in decimal degrees.
      - `lon` number, nullable, required: Longitude in decimal degrees.
      - `name` string, nullable, required: Location name when the provider reports one.
    - `updated_at` string, date-time, nullable, required: When the provider last updated the forecast, RFC 3339 UTC.
  - `op` string, required: Method name.
  - `op_version` integer, required: Method version that served the call.
  - `provider` string, required: Provider that actually served the call.
  - `raw` unknown
  - `raw_truncated` boolean
  - `request_id` string, required: Correlation id; quote it in support requests.
  - `took_ms` integer, required
  - `unsupported_fields` string[], required: Output paths this provider structurally does not supply; such fields are null for a different reason than 'missing on this record'.

## Other responses

- `400`: Validation error (unknown field, bad cursor, bad routing)
- `402`: Insufficient credits
- `404`: Not found (method, or upstream object)
- `429`: Rate limited upstream
- `502`: All providers failed
- `504`: Timed out

---

[API](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods.md) - [All operations](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/llms.txt) - [OpenAPI document](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/revisions/a7cf5b682fdd?raw)