# Get weather by city

> `GET /weather?city=` · Section: Data AI — Weather · PaperOffice AI API, release `R20261020.1917`.

`GET https://api.paperoffice.ai/latest/weather`

## Overview
Returns current weather and forecast for a **city name** (geocoded server-side).

Use **Tool-ID** `po_weather_by_city`. For raw coordinates use `po_weather_by_coordinates`.

## Required query parameters
- **city** — city name (e.g. `Berlin`)

Optional: **country** — ISO hint (e.g. `DE`); **lang** or **locale** — response language (default `en`).

## Example
`GET /weather?city=Berlin&country=DE&lang=de`

## Error examples
Missing city:

```json
{
"status": "error",
"code": "MISSING_LOCATION_INPUT",
"message": "Provide lat and lon (or latitude and longitude), or city (country optional)."
}
```

City could not be resolved:

```json
{
"status": "error",
"code": "GEOCODING_FAILED",
"message": "Could not resolve city to coordinates."
}
```

**API reference:** `po-weather-by-city` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `city` | string | Yes | City name to geocode (e.g. Berlin, Munich). |
| `country` | string | No | Optional ISO country hint to disambiguate the city (e.g. DE, US). |
| `lang` | string | No | Response language for condition text. (default: "en") |
| `locale` | string | No | Alias for lang. |

## Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

## Essentials (all endpoints)

- **Base URL:** `https://api.paperoffice.ai/latest` · **Auth:** `Authorization: Bearer po_sk_…` or `po_ut_…` (server-side only); browser code uses `po_pk_…` with an allowlisted `Origin`. No Bearer at all on a product API returns HTTP 403 `TIER_RESTRICTED`.
- **Errors:** HTTP 4xx/5xx with `status: "error"`, `code` and `message`. Retry 429 (`Retry-After`) and 5xx with exponential backoff; do not retry validation errors.
- **Jobs:** `client_wait=true` (default) holds the connection. HTTP 202 means the job is still running — poll `GET /job/get/{job_id}` every 5–10 s until `job_status` is `completed`, then read `result ?? job_result`. `processing_lane` sets the Start-SLA; legacy `priority` is not part of the public contract.
- **Billing:** every billable product call costs at least 5 credits; read `_billing.job.credits_billed` on billed responses.
- **Mutations** use `POST` with action paths (e.g. `POST /documents/document-delete`), not HTTP `DELETE`.

---

All endpoints: [llms.txt](https://api.paperoffice.ai/latest/docs/llms.txt) · Everything in one file: [llms-full.txt](https://api.paperoffice.ai/latest/docs/llms-full.txt) · [OpenAPI 3.1](https://api.paperoffice.ai/latest/docs/openapi.json) · This page: https://api.paperoffice.ai/latest/docs/endpoints/po-weather-by-city.md

*Generated 2026-10-20 from live API documentation (release `R20261020.1917`).*