Update to Vaisala Xweather API & Maps

{
  "name": "weather-api",
  "description": "Build and run Xweather Weather API request URLs for data.api.xweather.com from plain-language requirements. Use when a task mentions the Xweather or legacy Aeris API, weather endpoints such as observations, conditions, forecasts, alerts, lightning, air quality, tropical cyclones, tides, or road weather; asks for an API URL or query; needs help debugging an empty or failed request; asks about access costs, endpoint multipliers, rate limits, or allowance usage; or needs guidance for the hosted Xweather MCP server at mcp.api.xweather.com, including availability, connection, authentication, and tool scoping. Also covers Xweather's attribution requirement — the 'Powered by Vaisala Xweather' credit and logo rules that apply wherever Xweather data or imagery is displayed.",
  "included_files": [
    {
      "relative_path": "references/access-cost.md",
      "size_in_bytes": 7739
    },
    {
      "relative_path": "references/endpoints.md",
      "size_in_bytes": 39872
    },
    {
      "relative_path": "references/examples.md",
      "size_in_bytes": 46682
    },
    {
      "relative_path": "references/filters.md",
      "size_in_bytes": 84930
    },
    {
      "relative_path": "references/parameters.md",
      "size_in_bytes": 14120
    },
    {
      "relative_path": "references/recipes.md",
      "size_in_bytes": 8076
    },
    {
      "relative_path": "scripts/xwrequest.py",
      "size_in_bytes": 5273
    }
  ],
  "skill_md_contents": "---\nname: weather-api\ndescription: Build and run Xweather Weather API request URLs for data.api.xweather.com from plain-language requirements. Use when a task mentions the Xweather or legacy Aeris API, weather endpoints such as observations, conditions, forecasts, alerts, lightning, air quality, tropical cyclones, tides, or road weather; asks for an API URL or query; needs help debugging an empty or failed request; asks about access costs, endpoint multipliers, rate limits, or allowance usage; or needs guidance for the hosted Xweather MCP server at mcp.api.xweather.com, including availability, connection, authentication, and tool scoping. Also covers Xweather's attribution requirement — the 'Powered by Vaisala Xweather' credit and logo rules that apply wherever Xweather data or imagery is displayed.\ncompatibility: Skill instructions are provider-neutral. The bundled scripts/xwrequest.py needs Python 3 (standard library only) and network access to data.api.xweather.com.\nlicense: MIT\n---\n\n# Xweather Weather API URL builder\n\nTurn a description of wanted weather data into a correct `data.api.xweather.com` URL — and, when\ncredentials are available, execute it and return the data alongside the URL.\n\n## Request anatomy\n\n```\nhttps://data.api.xweather.com/{endpoint}/{action}/{:id}?{params}&client_id=…&client_secret=…\n```\n\n| Segment | Example | Notes |\n|---|---|---|\n| endpoint | `observations`, `conditions/summary` | *What* data. 59 of them — see `references/endpoints.md`. |\n| action | `closest`, `within`, `search`, `route`, `contains`, `affects` | *How* to look it up. Omitted entirely for `:id` and `:all`. |\n| `:id` | `seattle,wa`, `98109`, `44.97,-93.26`, `KMSP` | The place or record identifier. Goes in `p=` instead when an action occupies the path slot. |\n| params | `filter=`, `query=`, `fields=`, `limit=`, `from=`/`to=`, `format=` | Shape the result. |\n| credentials | `client_id` + `client_secret` | Query params on every request; no header form exists. |\n\n`api.aerisapi.com` is the legacy host and still works — always emit `data.api.xweather.com`.\n\n## Workflow\n\n1. **Extract from the prompt:** what data, which place(s), what time, and what shape of answer\n   (one record, N nearest, everything in an area, along a route, is-this-point-inside-a-polygon).\n2. **Pick the endpoint.** Use the intent map below; confirm against `references/endpoints.md`.\n3. **Pick the action** from the decision table below. Verify the endpoint actually supports it —\n   `endpoints.md` lists supported actions per endpoint, and an unsupported one returns\n   `not_implemented`.\n4. **Add parameters.** `filter` and `query` tokens are endpoint-specific; only use tokens listed for\n   that endpoint in `endpoints.md`. Read `references/filters.md` when choosing between similar\n   tokens (`standard` vs `all` for alerts, `day` vs `daynight` vs `mdnt2mdnt` for forecasts) — grep\n   for the `## /endpoint` heading rather than reading the whole file.\n5. **Sanity-check against a documented example.** `references/examples.md` has the API's own example\n   requests for every endpoint; `references/recipes.md` has 34 real-world queries by use case. If\n   the request resembles one, copy its structure instead of inventing parameters.\n6. **Emit the URL with its access cost** (see Access cost — always report it), then decide whether to\n   run it (see Executing the request).\n\nNever invent an endpoint, action, filter token, or query property. If unsure whether one exists,\ncheck `endpoints.md`, or refetch the live catalog:\n\n```bash\ncurl -s https://www.xweather.com/docs/api/weather-api/endpoints\n```\n\nThat JSON (`{ endpoint: {...}, action: {...} }`) is the authoritative, always-current list of every\nendpoint with its supported actions, params, filters, query properties, and sort fields — it is what\n`references/endpoints.md` was generated from. Use it when a user asks about something the reference\ndoesn't cover, or when a request fails with `invalid_request` / `not_implemented`.\n\n## Intent → endpoint\n\n| The user wants | Endpoint |\n|---|---|\n| \"What's the weather right now\" — blended current conditions, global | `/conditions/{place}` |\n| An actual reporting station's observation | `/observations/{place}` or `/observations/closest?p=…` |\n| Forecast — daily, day/night, hourly, 3-hourly | `/forecasts/{place}?filter=day\\|daynight\\|1hr\\|3hr` |\n| \"Will it rain in the next hour\" | `/conditions/{place}?filter=minutelyprecip` |\n| Hourly series across a past or future window | `/conditions/{place}?from=…&to=…` |\n| Yesterday's / a past day's high, low, precip total | `/conditions/summary/{place}?from=-1day` or `/observations/summary/{place}` |\n| Hour-by-hour history at a station | `/observations/archive/{place}?for=2024-06-05` (this endpoint takes `for=`, not `from`/`to`) |\n| 30-year climate normals | `/normals/{place}?filter=daily\\|monthly\\|annual` |\n| A plain-English weather summary sentence | `/phrases/summary/{place}` |\n| Warnings, watches, advisories | `/alerts/{place}` — counts across a region: `/alerts/summary` |\n| Lightning strikes near a point | `/lightning/closest?p=…&radius=25miles&limit=10` |\n| Lightning/thunderstorm nowcast, next ~60 min | `/lightning/threats` |\n| Radar-derived storm cells, hail, rotation, TVS | `/stormcells/{place}` · `/stormcells/closest` · `/stormcells/summary` |\n| Hail nowcast · localized threat summary | `/hail/threats` · `/threats/{place}` |\n| Confirmed storm damage reports (insurance, verification) | `/stormreports/search?query=state:…&filter=hail` |\n| Hurricanes / typhoons, active or historical | `/tropicalcyclones` · `/tropicalcyclones/archive` |\n| SPC severe convective outlook | `/convective/outlook/contains?p={place}` or `/convective/outlook/{place}` |\n| Is this location in a drought area | `/droughts/monitor/contains?p={place}` or `/droughts/monitor/{place}` |\n| Wildfires · fire weather outlook | `/fires/closest?p=…` · `/fires/outlook` |\n| Earthquakes | `/earthquakes/closest` or `/earthquakes/within` |\n| Air quality — current, forecast, historical, index only | `/airquality/{place}` · `/airquality/forecasts` · `/airquality/archive` · `/airquality/index` |\n| Health or activity index (migraine, golf, biking, …) | `/indices/{type}/{place}` |\n| Operational risk score for an activity | `/impacts/{activity}/{place}` |\n| Sunrise, sunset, twilight, moonrise · moon phases | `/sunmoon/{place}` · `/sunmoon/moonphases` |\n| Tides | `/tides/{place}?from=now&to=+1day` |\n| Offshore / marine — waves, swell, sea temp | `/maritime/{place}` · `/maritime/archive` |\n| Road conditions and driving risk | `/roadweather/{place}` · `/roadweather/analytics` · `/roadweather/conditions` |\n| River and lake gauges, flood stage | `/rivers/closest` · `/rivers/gauges` |\n| Solar irradiance for PV siting or yield | `/renewables/irradiance/summary` · `/archive` · `/tmy` |\n| Hail history for a location | `/hail/archive/{place}?from=…&to=…` |\n| Lightning climatology · wind-turbine strike risk | `/lightning/density/{place}` · `/lightning/turbinerisk/{place}?height=100m` |\n| Geocoding, place/ZIP/airport lookup, nearby cities | `/places/search` · `/places/closest` · `/places/postalcodes` · `/places/airports` · `/countries` |\n| Hyperlocal forecast from an Xcast sensor | `/xcast/forecasts/{device_id or place}` |\n| **Any of the above along a driving route** | append `/route` and pass `p=lat,lon;lat,lon;…` |\n\n`/conditions` vs `/observations` is the most common fork: `/conditions` is a modeled, gap-free blend\navailable for any coordinate on earth; `/observations` is what a physical station actually reported.\nReach for `/observations` when the user says \"station\", \"METAR\", \"airport\", or names a station id.\n\n## Action decision table\n\n| The question | Action | Shape |\n|---|---|---|\n| \"…for Denver\" | `:id` | `/alerts/denver,co` |\n| \"…everywhere / all active\" | `:all` | `/tropicalcyclones?filter=all` |\n| \"…nearest N to me\" | `closest` | `/lightning/closest?p=…&radius=25miles&limit=10` |\n| \"…inside this box / circle / polygon\" | `within` | `/earthquakes/within?p=43.23,-96.92,45.62,-91.31&limit=10` |\n| \"…matching these criteria, anywhere\" | `search` | `/observations/search?query=country:us&sort=temp:-1` |\n| \"…along this route\" | `route` | `/observations/route?p=44.96,-93.27;44.91,-93.5` |\n| \"…is this point inside a warned/outlook/drought area\" | `contains` | `/convective/outlook/contains?p=denver,co` |\n| \"…which towns does this storm/quake affect\" | `affects` | `/stormcells/affects?p=…` |\n\n**The location goes in `p=` for every action except `:id` and `:all`** — the path slot after the\nendpoint is where the action name lives, so `/convective/outlook/contains/denver,co` fails with\n`invalid_request: Invalid Action: contains/denver,co`. It's `/convective/outlook/contains?p=denver,co`.\n\nTwo more traps: `limit` defaults to **1**, so `closest`/`search`/`within` without it return a single\nrecord; and `closest` with too small a `radius` returns `warn_no_data` rather than an error.\n\nOn polygon endpoints, `/{endpoint}/{place}` (the `:id` form) is a documented shorthand for\n`contains` — `/droughts/monitor/san diego,ca` ≡ `/droughts/monitor/contains?p=san diego,ca`.\n\n## Parameter essentials\n\n| Parameter | Use |\n|---|---|\n| `p` | The place, when an action occupies the path slot. Also carries `within` geometry and `route` point lists. |\n| `limit` / `skip` | Primary result count / offset. **Default `limit` is 1.** |\n| `plimit` / `pskip` / `psort` | Same, for sub-elements (`periods` entries). |\n| `radius` / `minradius` / `mindist` | Search radius (`25miles`, `10km`), donut inner radius, minimum spacing between returned points. |\n| `filter` | Endpoint-specific selectors. `,` = AND, `;` = OR. |\n| `query` | Value filtering, `property:value`. `,` = AND, `;` = OR. |\n| `sort` | `property:-1` descending, `:1` ascending. |\n| `from` / `to` / `for` | Range, or a single valid time. `now`, `today`, `friday`, `+3days`, `-12hours`, `2024-03-23`, `2024-06-05 16:00:00`. |\n| `fields` | Comma list of dot-notated properties to return. |\n| `format` | `json` (default), `geojson`, `csv`, `tsv`. |\n\nTwo things that bite:\n\n- **`query=` values are metric**, regardless of which units you read back out. `temp`/`dewpt` in\n  Celsius, `wind`/`gust` in knots, `pressure` in millibars. `query=temp:30` is ≥ 30 °C.\n- **A bare number in `query=` means \"greater than or equal\"**, not \"equals\". Use `min:max` for a\n  range, `!` for not-equal, `^` for starts-with, `NULL`/`!NULL` for null checks.\n\nFull detail — every parameter, all place formats, date forms, query operators, sorting, batch\nrequests, response envelope, error and warning codes, cost headers — is in\n`references/parameters.md`.\n\n## Access cost — always report it\n\nOne HTTP request is not one access. Every URL you hand over must come with what it will cost against\nthe subscription allowance, unprompted — a `/impacts` request costs 25× a `/forecasts` one, and a\n200-point route request costs 200×, which is not something a user should discover from an invoice.\n\n```\naccesses = endpoint multiplier × spatial multiplier × temporal multiplier\n```\n\n**The spatial multiplier is always 1** — no current endpoint uses it, so query area, radius and\ngeometry never affect cost. What's left is:\n\n```\naccesses = endpoint multiplier × intervals requested\n```\n\nThe **endpoint multiplier** is a fixed constant: `Cost: xN` on each entry in\n`references/endpoints.md`, or the grouped table in `references/access-cost.md`. The **temporal\nmultiplier** is the number of days or hours a single request covers, on endpoints that return a series\nover a range — `/conditions/summary` bills one access per day, so a 30-day request is 30 accesses, not\none.\n\nBoth are knowable up front, so give a real number:\n\n> `https://data.api.xweather.com/airquality/beijing,cn?filter=china&client_id={client_id}&client_secret={client_secret}`\n> **Cost: 5 accesses** — `/airquality` is ×5, one point in time.\n\n> `https://data.api.xweather.com/conditions/summary/minneapolis,mn?from=-30days&to=now&client_id={client_id}&client_secret={client_secret}`\n> **Cost: 30 accesses** — `/conditions/summary` is ×1 and bills one access per day, so 30 days of\n> summaries is 30 accesses. Shortening the range is the only way to reduce it.\n\n> `https://data.api.xweather.com/lightning/within?p=43.23,-96.92,45.62,-91.31&limit=500&client_id={client_id}&client_secret={client_secret}`\n> **Cost: 10 accesses** — `/lightning` is ×10. The multi-state bounding box costs nothing extra; area\n> is not a cost factor.\n\nDon't tell anyone to shrink a radius or tighten a bounding box to save accesses — it doesn't work.\nWhere you're unsure whether an endpoint bills per interval, name the range as the thing that could\nmultiply the cost and point at `X-Cost-Tokens`, rather than inventing a number.\n\nWhen you actually run the request, `X-Cost-Tokens` is the exact charge — quote it instead of the\nestimate.\n\nCases with an exact documented rule, worth calling out whenever they apply:\n\n- **`route` charges one access per point**, times the endpoint multiplier. 200 points against\n  `/roadweather/analytics` (×10) is ~2,000 accesses. Always state the point count and the product.\n- **`batch` charges each sub-request separately.** It saves round trips, not accesses. Max 31.\n- **4xx and 5xx cost nothing.** Only 2xx is charged, so retrying a corrected URL is free.\n- **`fields=` and `limit` don't reduce cost.** They shrink the payload, not the charge.\n\nThe expensive endpoints, worth flagging when one is chosen: `/impacts` (×25); `/hail/archive`,\n`/hail/threats`, `/lightning/analytics` (×12); `/lightning`, `/lightning/archive`,\n`/lightning/threats`, `/renewables/irradiance/summary`, `/roadweather/analytics` (×10); `/airquality`\nand its archive/forecasts, `/maritime/archive`, `/roadweather/conditions` (×5). If a cheaper endpoint\nanswers the same question — `/airquality/index` (×1) for just the index, `/lightning/summary` (×1) for\naggregate counts, `/roadweather` (×1) without analytics fields — say so.\n\nFull model, the complete multiplier table, and cost-reduction tactics: `references/access-cost.md`.\n\n## Executing the request\n\nDefault behavior with no credentials: **produce the URL only**, with `{client_id}` and\n`{client_secret}` placeholders, and explain what it returns. Mention that keys from the API Keys page\nof https://data.portal.xweather.com/account/keys let you run it and return live data.\n\nWhen the user supplies a client id and secret — in the prompt, in a `.env`, or already exported —\nrun the request and return **both the response and the URL**. Never leave the URL out; it is half\nthe deliverable.\n\nPreferred: put the credentials in the environment and use the bundled helper, which keeps the secret\nout of the command line and out of its own output.\n\n```bash\nexport XWEATHER_CLIENT_ID='…' XWEATHER_CLIENT_SECRET='…'\npython3 scripts/xwrequest.py '/observations/seattle,wa?filter=allstations&limit=3'\n```\n\nInvoke it as `python3 scripts/xwrequest.py`, resolved relative to this skill's directory. Some\nclients also expose it as a bare `xwrequest` command on PATH — use that if available, but don't\nassume it.\n\nIt prints the URL with credential placeholders, the HTTP status, the accesses charged with the\n`endpoint`/`spatial`/`temporal` breakdown, the remaining minutely and period allowance, and the\npretty-printed body. `--post file.json` sends a JSON body for long `/route` requests; `--raw` skips\npretty-printing for CSV/TSV.\n\nPlain `curl` works too, with the credentials referenced as shell variables rather than pasted:\n\n```bash\ncurl -s \"https://data.api.xweather.com/observations/seattle,wa?limit=3&client_id=$XWEATHER_CLIENT_ID&client_secret=$XWEATHER_CLIENT_SECRET\"\n```\n\n### Handling credentials\n\n- **Show the URL with `{client_id}` / `{client_secret}` placeholders in your reply**, not the literal\n  key values — replies get pasted into tickets, chats, and commits. If the user explicitly asks for\n  a fully populated copy-paste URL, give it to them; that's their call to make.\n- Don't write credentials into a file, a script, or a committed config unless asked. If they're\n  already in a `.env` that the project reads, use that.\n- A `401` / `invalid_client` means the keys are wrong. `unauthorized_namespace` means the keys are\n  valid but the request came from outside the domain or bundle id they were registered against —\n  common when testing server-side keys locally, and not something a different URL will fix.\n\n### What to report back\n\n1. The URL, with credential placeholders.\n2. **The access cost** — `X-Cost-Tokens` when the request ran, the endpoint-multiplier floor when it\n   didn't. This goes in every reply that contains a URL, whether or not the user asked.\n3. A one-line reading of the data that answers what was actually asked (\"62 °F, overcast, wind\n   9 mph from the NNE at KBFI as of 14:53 local\"), not just a JSON dump.\n4. The relevant slice of the response — trimmed if it's long, since a 168-period hourly forecast is\n   not a useful thing to paste in full.\n5. Anything worth knowing: warnings in the `error` field even on a 200, a cost that's high because of\n   the time range, remaining allowance if it's running low, or an empty result that means \"widen the\n   radius\".\n\nIf the reply contains several URLs, give each its own cost line and a total.\n\n## Debugging a request that doesn't work\n\n| Symptom | Likely cause |\n|---|---|\n| `invalid_location` | Place string didn't resolve — try another supported format (ZIP, `city,state`, lat/lon). |\n| `warn_location` on a 200 | No state given for a US/CA city; the API guessed by population. Add the state. |\n| `warn_no_data`, empty array | `closest`/`within` radius too small, or the time window has no records. Widen it. |\n| One result when several were expected | `limit` defaults to 1. |\n| `not_implemented` | That action isn't supported on that endpoint — check `endpoints.md`. |\n| `warn_invalid_param`, parameter silently dropped | Parameter not supported on that endpoint, or not included in the account's plan. |\n| `insufficient_scope` | Dataset isn't on the subscription (historical add-on, premium polygons, etc.). |\n| HTTP 200 with `invalid_request: Invalid Action: …` | A place was put in the path *after* an action name. Move it to `p=`. |\n| `404` | Endpoint path is wrong. |\n| `429` with `maxhits_min` / `maxhits` | Per-minute or subscription-period access limit hit — check the `X-RateLimit-*` headers and see `access-cost.md`. |\n| Nothing wrong, but huge response | Add `fields=`, lower `limit`/`plimit`. |\n\n## The Xweather MCP server — an alternative to building URLs\n\nXweather runs a hosted MCP server at **`https://mcp.api.xweather.com/mcp`**. Connected to an MCP\nclient, it turns a plain-language question into the necessary Xweather calls directly — no endpoint,\naction, filter, or field names to get right.\n\nRaise it when the user is asking questions *of* the weather rather than building an application\nagainst the API: \"what's the lightning risk in Tampa,\" \"compare this week's rainfall for Seattle and\nPortland.\" Keep using this skill for URLs when they need a request to embed in their own code, want to\nunderstand the API's structure, or are debugging an existing integration. The two complement each\nother — the MCP server answers questions; this skill produces artifacts.\n\n**It is not bundled with this plugin.** Adding it is one command:\n\n```bash\nclaude mcp add --transport http xweather https://mcp.api.xweather.com/mcp \\\n  --header \"Authorization: Bearer CLIENT_ID_CLIENT_SECRET\"\n```\n\nAdd `--scope user` to make it available across all projects, or `--scope project` to share it with a\nrepo via `.mcp.json`.\n\n### Authentication\n\nThe token is the **client id and secret joined by a single underscore** — `abc123_def456` — not two\nseparate parameters. Three ways to pass it:\n\n| Method | When |\n|---|---|\n| `Authorization: Bearer <client_id>_<client_secret>` | Preferred for clients that support custom request headers. |\n| `?api_key=<client_id>_<client_secret>` | For clients that cannot set custom request headers. |\n| OAuth 2.0 | Supported, but verify current Xweather OAuth guidance before recommending it because client interoperability varies. |\n\n### Scoping the tools\n\nSix tag groups exist: `general` (current conditions, impacts, air quality), `forecast`, `summary`\n(aggregations), `tropical`, `lightning`, `roadweather`. Filter them with query parameters:\n\n```\nhttps://mcp.api.xweather.com/mcp?include_tags=forecast,summary\n```\n\nAlso `exclude_tags`, `include_tools`, `exclude_tools` (exact tool names like\n`xweather_get_current_weather`). Precedence runs `exclude_tools` → `exclude_tags` → `include_tools` →\n`include_tags`.\n\nRecommend scoping when the user has other MCP servers connected — loading all six groups crowds the\nmodel's tool choices, which is the reason Xweather documents the filters at all.\n\n### Diagnosing a failed connection\n\n| Response | Meaning |\n|---|---|\n| `401 invalid_token` | Missing or wrong token. The body suggests clearing tokens and re-registering — that's generic MCP OAuth advice and doesn't apply to bearer-key auth; check the token value instead. |\n| `500` | Usually a malformed token: both halves and exactly one underscore are required. |\n| `403` | Valid credentials, but the subscription doesn't include MCP access. |\n\nMCP access may need a specific subscription tier, so \"is it available to me?\" is an account question\n— point the user at their account executive rather than guessing.\n\n## Attribution is required\n\nXweather requires attribution wherever its data or imagery is displayed. This applies to **all\nproducts** — Weather API, Raster Maps, and MapsGL alike. Build it into anything you produce, and say\nso when handing over code or URLs that will end up in front of users.\n\nThe minimum is a link to `https://www.xweather.com/` reading \"Powered by Vaisala Xweather\":\n\n```html\n<a href=\"https://www.xweather.com/\" target=\"_blank\" title=\"Powered by Vaisala Xweather\">Powered by Vaisala Xweather</a>\n```\n\nThe logo may be substituted for the \"Xweather\" text. Light and dark variants exist in SVG and PNG:\n\n```html\n<a href=\"https://www.xweather.com/\" target=\"_blank\" title=\"Powered by Vaisala Xweather\">\n  <img src=\"https://www.xweather.com/assets/logos/vaisala-xweather-logo-dark.svg\" alt=\"Vaisala Xweather\" height=\"40\" />\n</a>\n```\n\nSwap `-dark` for `-light` over a dark background, or `.svg` for `.png`. Using the logo brings rules:\nkeep it unmodified, leave at least a **10px buffer** of space around it, and only adjust lightness or\nopacity in greyscale. Don't rotate it, don't recolour it (monotone black or white excepted), and don't\nuse the symbol without the Xweather name.\n\nFull guide: https://www.xweather.com/docs/weather-api/resources/attribution\n\n## Reference files\n\n- `references/endpoints.md` — every endpoint: description, coverage, data range, update interval,\n  cost multiplier, and the exact supported actions / params / filters / query props / sort fields.\n- `references/access-cost.md` — the access-cost model, every endpoint grouped by multiplier, what\n  raises the spatial and temporal factors, the exact `route`/`batch`/error rules, cost-reduction\n  tactics, and the cost + rate-limit headers.\n- `references/parameters.md` — request anatomy, every parameter, all 8 actions with their geometry\n  and POST forms, place formats, date forms, query operators, sorting, output formats, batch\n  requests, response envelope, error/warning codes, cost headers.\n- `references/filters.md` — what each endpoint's `filter` tokens and `query` properties actually\n  mean. Search for the `## /endpoint` heading you need rather than reading it end to end.\n- `references/examples.md` — the API docs' own example requests for every endpoint, with\n  descriptions. The best model for correct URL shape.\n- `references/recipes.md` — 34 real-world queries by industry/use case, plus the patterns behind\n  them.\n- `scripts/xwrequest.py` — runs a request using `XWEATHER_CLIENT_ID` / `XWEATHER_CLIENT_SECRET` from\n  the environment; prints the placeholder URL, status, accesses charged with the multiplier\n  breakdown, remaining allowance, and the body.\n"
}