# atlashot — data on maps, from a link

Turn `{region: value}` data into a shareable choropleth map image with a single GET URL. No account, no API key, no code execution.

## One complete example

```
https://atlashot.pages.dev/m?map=europe&title=Electricity+prices+2026&unit=EUR/MWh&source=ENTSO-E&d=AT:241,BE:189.5,DE:210,FR:198,PL:150,ES:165,IT:220,NL:195,SE:96,NO:88
```

Opening that URL renders a colored map of Europe with a title, legend, and unit label, and offers branded SVG/PNG downloads.

Add `&format=svg` to the same URL to get the raw SVG image back (for direct embedding), or `&format=json` for machine-readable diagnostics.

## URL anatomy

`https://atlashot.pages.dev/m?map=<mapset>&d=<CODE:value,...>&title=...`

## Parameters

| param | required | type | default | allowed | meaning |
|---|---|---|---|---|---|
| `map` | **yes** | string | — | a map set id from the table below (e.g. world, europe, us, ro) | Which map to draw. |
| `d` | **yes** | string | — | comma-separated CODE:value pairs | The data. CODE is ISO 3166-1 alpha-2 for countries (DE, FR) or ISO 3166-2 for subdivisions (US-CA, RO-CJ). Values: numbers for color scales, or short text labels for categorical maps. Aliases accepted per map set: plain region names everywhere; ISO alpha-3 + ISO numeric (world, europe); EL/UK NUTS-0 (europe); FIPS numeric + bare postal (us); NUTS-3 codes + bare county codes (ro). |
| `title` | no | string | none | any text (URL-encoded, + for space) | Map title, rendered into the image. |
| `subtitle` | no | string | none | any text | Smaller line under the title. |
| `unit` | no | string | none | any short text | Unit label shown with the legend (e.g. EUR/MWh, %). |
| `source` | no | string | none | any short text | Data source credit, rendered next to the attribution. |
| `palette` | no | string | blues (numeric), rdbu (mixed-sign), tableau (text) | blues, greens, oranges, purples, reds, viridis, rdbu, brbg, puor, tableau | Color palette. Sequential for all-positive numbers, diverging (rdbu/brbg/puor) for mixed-sign, tableau for categories. |
| `scale` | no | string | quantile (quantize over a symmetric domain for mixed-sign data) | quantile, quantize, linear, threshold:10,20,50 | How values map to color classes. threshold takes explicit cut points. |
| `classes` | no | integer | 5 | 3–9 | Number of color classes. |
| `domain` | no | string | data min,max (symmetric around 0 for mixed-sign data) | min,max (two numbers) | Override the scale extent. |
| `format` | no | string | ,.2~f | a d3-format specifier (.1f, .0%, ~s) — or the reserved values json and svg | Number format for legend labels. Reserved values change the response instead: format=json returns machine-readable diagnostics (application/json); format=svg returns the map itself as a raw SVG image (image/svg+xml), directly embeddable in <img> tags. |
| `embed` | no | flag | 0 | 1 | Render only the map (for iframes) — no page chrome. |
| `v` | no | integer | 1 | 1 | URL format version. |

## Map sets

| id | coverage | regions | region codes |
|---|---|---|---|
| `world` | World — countries | 175 | [codes](https://atlashot.pages.dev/docs/maps/world.md) |
| `europe` | Europe — countries | 46 | [codes](https://atlashot.pages.dev/docs/maps/europe.md) |
| `us` | United States — states | 51 | [codes](https://atlashot.pages.dev/docs/maps/us.md) |
| `ro` | Romania — județe | 42 | [codes](https://atlashot.pages.dev/docs/maps/ro.md) |

## Examples

### European electricity prices (sequential scale, unit)

Country codes are ISO alpha-2; unit shows in the legend.

```
https://atlashot.pages.dev/m?map=europe&title=Electricity+prices+2026&unit=EUR/MWh&source=ENTSO-E&d=AT:241,BE:189.5,DE:210,FR:198,PL:150,ES:165,IT:220,NL:195,SE:96,NO:88
```

### World temperature anomaly (diverging, mixed-sign)

Mixed-sign values pick the diverging red-blue palette automatically.

```
https://atlashot.pages.dev/m?map=world&title=Temperature+anomaly&unit=%C2%B0C+vs+1991-2020&d=US:1.2,CA:1.8,RU:2.1,BR:0.6,AU:0.9,IN:0.7,CN:1.1,ZA:0.8,AR:-0.2,GL:2.9
```

### US states, categorical values

Text values make a categorical map; codes are US-XX.

```
https://atlashot.pages.dev/m?map=us&title=Time+zones+(sample)&d=US-CA:Pacific,US-NV:Pacific,US-CO:Mountain,US-TX:Central,US-IL:Central,US-NY:Eastern,US-FL:Eastern
```

### Romanian counties with explicit thresholds

Subdivision codes are RO-XX; threshold sets the class cut points.

```
https://atlashot.pages.dev/m?map=ro&title=Population+density&unit=per+km%C2%B2&scale=threshold:50,100,200&d=RO-B:8093,RO-CJ:105,RO-TM:80,RO-IS:146,RO-CT:96,RO-BV:115
```

### Percent-formatted, fixed domain

format styles legend labels; domain fixes the scale extent.

```
https://atlashot.pages.dev/m?map=europe&title=Renewables+share&scale=quantize&format=.0%25&domain=0,1&d=NO:0.98,SE:0.68,FR:0.25,DE:0.46,PL:0.21,ES:0.5
```

## Instructions for AI agents

- Region codes are ISO codes, not names: RO-CJ not "Cluj county", US-CA not "California" — names usually resolve as a courtesy, but ISO codes are the contract. Do not invent codes.
- Subdivision codes include the country prefix: US-CA, RO-CJ — never bare CA or CJ in documentation examples (bare forms resolve, but are ambiguous across map sets).
- Do not invent parameters. The full list is above; anything else is ignored with a warning.
- Keep URLs under 2,000 characters (hard limit 4,000). Every listed map set fits comfortably: a full world dataset is ~1,600 characters.
- Values are plain numbers (189.5) or short text labels (high) — no percent signs, no thousands separators, no quotes inside d=; labels must not contain , ; : = or newline characters (the d= grammar reserves them).
- Use commas between pairs and a colon inside each pair: d=DE:83.2,FR:68.6 — spaces are allowed but must be URL-encoded (+).
- The URL is data, not code: never base64/deflate the payload; write it out plainly.
- To verify a URL before sharing it, append &format=json and fetch it: the response is real JSON (application/json) reporting ok, matched/total, unmatched codes with suggestions, and a corrected example. HTTP 400 means required parameters are missing or wrong.

## Errors and diagnostics

Rendering is forgiving: bad rows are skipped with a warning, the rest of the map renders. Diagnostics are available three ways:
1. A visible banner on the page (humans).
2. An embedded `<script type="application/json" id="diagnostics">` block in the rendered page (agents that fetch and execute the page).
3. `&format=json`: the same URL returns a true JSON response (`application/json`) — `{ok, map, matched, total, unmatched: [{input, suggestion}], errors, warnings, fix, example, docs_url}`. HTTP 200 when the map renders (warnings included), HTTP 400 when required parameters are missing or wrong.

A JSON Schema for the request payload: https://atlashot.pages.dev/schema/map-request.schema.json
An OpenAPI 3.1 description of GET /m: https://atlashot.pages.dev/openapi.json
Machine-readable docs: https://atlashot.pages.dev/llms.txt (index) · https://atlashot.pages.dev/llms-full.txt (everything inlined)