raster-maps

Xweather Raster Maps URL builder

Turn a description of wanted weather imagery into a maps.api.xweather.com URL — as a standalone static image or as a tile template for an interactive mapping library.

This is a different product from the Weather API: different host, different URL grammar, and credentials sit in the path, not in the query string.

https://maps.api.xweather.com/{client_id}_{client_secret}/{layers}/…/{offset}.{format}

Two output methods — ask which one

Every Raster Maps request is one of two shapes, and they are not interchangeable:

	Static map	Map tiles
Produces	A single finished image	A 256×256 tile template a library fetches many of
Use when	Email, report, dashboard panel, <img> tag, Slack, PDF	Leaflet / Mapbox / Google Maps / OpenLayers / Apple Maps
Path	{layers}/{w}x{h}/{place},{zoom}/{offset}.{fmt}	{layers}/{z}/{x}/{y}/{offset}.{fmt}
Interactive	No — no pan or zoom	Yes

If the user hasn't said which one they want, ask before generating anything. Use Ask a direct either/or question — a structured-choice prompt if the agent has one, plain text otherwise. Don't guess from weak signals and don't produce both by default — a tile template pasted into an <img> tag renders one 256-pixel square, and a static URL handed to Leaflet fails outright.

Signals strong enough to skip the question: the user names a mapping library, says "tile layer" or "XYZ", or gives {z}/{x}/{y} (→ tiles); or names pixel dimensions, says "image", "PNG for a report", or shows an <img> tag (→ static).

Workflow

1. Determine the output method — ask if not already clear (above).
2. Pick the layers. Use the intent map below and confirm codes against references/layers.md. Order matters: they composite left to right, so base map first, weather next, labels last.
3. Add the geography. Static: place,zoom or a south,west,north,east bounding box. Tiles: the library substitutes {z}/{x}/{y} — leave the placeholders in.
4. Add the time offset. current unless the user wants past or forecast imagery.
5. Pick the format. png for tile overlays (transparency is mandatory); png or jpg for static maps that include their own base layer.
6. Apply modifiers if the request implies them — opacity, blur, blend, recolour. See references/modifiers.md.
7. Report the URL with its map-unit cost (see Map units), then handle credentials (see below).
8. Include the attribution. Any markup you hand over — an <img> tag, a tile layer, a template — needs the Xweather credit alongside it. See "Attribution is required" below.