# Polygrid Maps

> Ephemeral, shareable web maps for AI agents. POST GeoJSON or place names, get back a link and a markdown snippet to give the user (plus a PNG preview on request). No API key. Maps are deleted after 30 days without views, and can be changed later on the same link with the edit token. Using Claude Code, Codex, Cursor, Gemini CLI or claude.ai? Install the plugin (MCP server + create-map skill) from https://github.com/agilek/polygrid-maps; setup per client: https://maps.polygrid.dev/docs/agents.

Base URL: https://maps.polygrid.dev

## How to answer the user (read this first)

- Don't mention files, JSON, backups or tokens to the user; changes are a PUT on the same map, no backups needed.
- Keep the whole create response, not just `url`: `edit_token` (and `edit_url`) are returned only once, by create. Save it (e.g. `curl … -o map.json`) so you can update the map later in this conversation. If you lost it, say you can't change that map and ask for its private edit link; don't silently make a replacement map.
- When the user asks to change, add to or restyle a map you made in this conversation (add routes, add places, make it dark, rename...), update that map in place with its edit token: same link, no new map. Create a new map only when they ask for a separate or new one.
- Multi-day or multi-leg routes go into one map with `routes` (`route_view` tabs), not one map per day.
- Travel mode: use the mode the user states (drive/car/road trip → `car`; bike/cycle → `bike`; walk/on foot/hike/run → `foot`; metro/bus/tram/train/public transport → `transit`). If they don't say: city sightseeing → `foot` within an area and `transit` for hops over ~2 km (give that place `"mode": "transit"`); road trips, countryside or a list of towns → `car`; running route → `foot`; bike tour → `bike`. Never default to car inside a city. Families with kids or limited mobility: shorter walks, more transit. Say the mode in one plain line and offer the switch, e.g. "Walking routes with metro between areas; tell me if you'll drive and I'll switch them to car." Switching updates the same map in place: `update_map` with `changes: {"routes": [{"name": "Day 1", "mode": "car"}, {"name": "Day 2", "mode": "car"}]}`.
- Your reply to the user, in this order:
  1. Only where your chat really displays outside images (not claude.ai, Claude Desktop, Cowork or terminals; when unsure, skip it): `preview_markdown` (the map thumbnail, linking to the map).
  2. The share link (`url`) on its own line.
  3. One line saying what the map shows.
  4. For maps with routes: one plain line with the travel mode and the offer to switch, e.g. "Walking routes with metro between areas; tell me if you'll drive and I'll switch them to car."
  5. Any `warnings`, in plain words.
  6. `edit_url` as "your private edit link (lets you change the map later; don't share it)". Never show the raw `edit_token`.
  7. That tapping a place shows its details (photo, address, hours, links, Directions), and one or two tweaks (another basemap, categories with colors, a route).
- No technical narration. Never write these in the reply: API, endpoint, token, edit token, JSON, curl, file names or paths, bounding box, proxy, plugin, tool names. To say you can update the map later, write "I can still change this map for you" (not that you saved a token or a file).
- If you cannot reach the API from your environment, don't explain why. Give the user the publish link `https://maps.polygrid.dev/new#c=…` (see below) and say: "Your map is ready, open this link and press Publish map".
- If you have a built-in browser, open the map's share link in it as your very last step, so the chat shows a live preview card of the map. Don't navigate anywhere after it.

## Create a map

`POST https://maps.polygrid.dev/v1/maps` with a JSON body. At least one of `data`, `places` or `areas` is required.

Named places (geocoded for you; prefer this over inventing coordinates):

```bash
curl -X POST https://maps.polygrid.dev/v1/maps -H 'Content-Type: application/json' -d '{
  "title": "Weekend in Prague",
  "places": ["Prague Castle", "Charles Bridge, Prague", "Old Town Square, Prague"],
  "connect": true
}'
```

`connect: true` draws a straight line through the places in order and numbers the pins 1..n. `"route": "car"` (or `bike`, `foot`, `transit`) follows roads instead and adds distance and travel time, e.g. `{"places": ["Prague", "Bratislava"], "route": "car"}` → "2 places and a 335 km drive (about 3 h 36 min)". If a place is unroutable (>5 km from a road), it falls back to straight lines with a warning. A place can also be an object with its own style: `{"q": "Charles Bridge, Prague", "title": "Bridge", "marker-color": "#e11d48"}`. Max 50 places. Add city/country to names to avoid ambiguity. `transit` (aliases `public_transport`, `metro`, `subway`, `bus`, `tram`, `train`) is not routed: see the mode rules under `routes` below.

Several routes on one map (a trip with a route per day, or alternatives to compare): use `routes` instead of one map per route.

```bash
curl -X POST https://maps.polygrid.dev/v1/maps -H 'Content-Type: application/json' -d '{
  "title": "Barcelona with kids",
  "routes": [
    {"name": "Day 1", "mode": "foot", "places": ["Sagrada Família, Barcelona", "Park Güell, Barcelona"], "color": "#2563eb"},
    {"name": "Day 2", "mode": "foot", "places": ["Casa Batlló, Barcelona", {"q": "La Boqueria, Barcelona", "title": "Lunch at La Boqueria"}]}
  ],
  "route_view": "tabs"
}'
```

- Each route: `name` (≤60 chars, unique; required with 2+ routes), `mode` (`car`, `bike`, `foot`, `transit`; default `foot`; aliases `driving`, `cycling`, `walking`, `public_transport`, `metro`, `subway`, `bus`, `tram`, `train`; an unknown mode is a 400 listing them), `places` (same forms as top-level `places`, 2–25), optional `color` (auto palette otherwise), `remove: true`. Stops are numbered 1..n per route and routed with OSRM (straight-line fallback per route, with a reason).
- Per-leg modes: a place in `places` may be an object with `mode`, the mode of the leg ARRIVING at that place; it overrides the route's `mode` for that one leg (`mode` on the first place is ignored). Example, a city day on foot with one metro hop:
  `{"name": "Day 1", "mode": "foot", "places": ["Sagrada Família, Barcelona", {"q": "Park Güell, Barcelona", "mode": "transit"}, {"q": "Gràcia, Barcelona", "mode": "foot"}]}`
- `transit` draws a dashed straight line between the two stops with a 🚇 badge; there are no times (distance only, no duration). Tapping it shows "Public transport" and a "Public transport directions" button that opens Google or Apple Maps for that hop.
- Runs: consecutive legs with the same mode are one run. Each car, bike or foot run is one OSRM request through its stops; each transit leg is its own dashed line and never goes to OSRM. At most 15 routed runs per request: more is a 400, so merge legs, use fewer routes, or add routes in a later update.
- Limits: 6 routes per map, 50 places per request in total (top-level `places` plus all routes).
- `route_view`: `tabs` (one route at a time, with "All · Day 1 · Day 2" tabs; for days of a trip) or `together` (all routes visible, legend chips toggle each; for comparing alternatives, e.g. 3 bike route options). Default `tabs` with 2+ named routes, else `together`. Viewer URL: `?route=2`, `?route=Day%202` or `?route=all` opens a route; `?route_view=together` overrides the mode.
- Top-level `places`, `data` and `areas` can be combined with `routes`: they are shared and shown with every route. Top-level `route` / `connect` still work as before for a single route through `places`.
- The response has `routes`: `[{"name": "Day 1", "mode": "foot", "color": "#2563eb", "status": "routed", "distance_m": 4200, "duration_s": 3100, "stops": 2}]` (`status` is `routed` or `straight`, with a `reason` when straight). Each route also has `mode` (the single mode, or `"mixed"` when legs differ), `legs` (`[{"from": "Sagrada Família", "to": "Park Güell", "mode": "transit", "status": "transit"}, {"from": "Park Güell", "to": "Gràcia", "mode": "foot", "status": "routed", "distance_m": 1200, "duration_s": 900}]`, stop titles, in order) and `totals` per mode, e.g. `{"foot": {"distance_m": 3200, "duration_s": 2700}, "transit": {"legs": 2}}`. `distance_m` and `duration_s` of the route sum the car, bike and foot legs only; transit has no duration.
- Add routes to an existing map (same link): PUT the `GET` body with `routes` appended, or MCP `update_map` with `changes: {"routes": [ …new routes only… ]}`. Existing routes and features are kept; routes you do not mention stay as they are. A route given with `places` replaces the route of the same name. `{"name": "Day 1", "remove": true}` deletes a route; `{"name": "Day 1", "color": "#e11d48"}` or `{"name": "Day 1", "mode": "bike"}` without `places` recolors or re-routes an existing route from its stops (unknown name: 400). To switch a whole route to another mode in place, e.g. to driving, send `{"name": "Day 1", "mode": "car"}` with no `places` (MCP `update_map` changes, or PUT): it is re-routed from its stops with every leg set to that mode, transit legs included; per-place modes are replaced (send `places` to mix modes again). Nothing is re-geocoded and the link stays the same.

GeoJSON (FeatureCollection, Feature, GeometryCollection or a bare geometry, including Multi*). Coordinates are `[longitude, latitude]`:

```bash
curl -X POST https://maps.polygrid.dev/v1/maps -H 'Content-Type: application/json' -d '{
  "data": {"type": "LineString", "coordinates": [[14.4005, 50.0908], [14.4114, 50.0865], [14.4208, 50.0875]]},
  "basemap": "dark"
}'
```

Styled features (simplestyle-spec properties on each feature):

```bash
curl -X POST https://maps.polygrid.dev/v1/maps -H 'Content-Type: application/json' -d '{
  "title": "Coffee and parks",
  "data": {"type": "FeatureCollection", "features": [
    {"type": "Feature", "properties": {"title": "Café Louvre", "description": "Since 1902", "marker-color": "#b45309", "marker-symbol": "☕"},
     "geometry": {"type": "Point", "coordinates": [14.4193, 50.0820]}},
    {"type": "Feature", "properties": {"title": "Letná Park", "fill": "#16a34a", "fill-opacity": 0.3, "stroke": "#15803d"},
     "geometry": {"type": "Polygon", "coordinates": [[[14.410, 50.096], [14.432, 50.096], [14.432, 50.100], [14.410, 50.100], [14.410, 50.096]]]}}
  ]}
}'
```

### Request fields

- `areas`: `{within, level?, values?}` draws real administrative boundaries (from Wherebox; data © OpenStreetMap contributors and Overture Maps Foundation, credited automatically in the map attribution). `within` is an area name ("Berlin", "Praha, Czechia", "Bavaria") or a Wherebox id ("osm:r62422"); if another area with the same name is as significant, a warning lists its id. `level` is `"auto"` (default: the first level with 2+ parts, e.g. Berlin → 12 districts, Czechia → 14 regions, Praha → 57 districts), an OSM admin level 2–11, or `"none"` (just the outline). `values` is an object keyed by area name or id: a number becomes the property `value` (and `color_by` defaults to `"value"`); an object merges its properties (e.g. `{"population": 1, "description": "…"}`). Matching ignores case and accents, then falls back to a unique partial match ("Kreuzberg" → "Friedrichshain-Kreuzberg"); unmatched keys produce a warning listing the area names. Every area has `title`, `population`, `area_km2` (and a hidden `area_id`), so `"color_by": "population"` works with no data at all. With `areas` the defaults are basemap `blank` (locked), labels on (up to 60 areas) and the title "<Area> by <color_by>" or the area name. Can be combined with `data` / `places` (pins and lines are drawn on top). Errors: 400 "No area named …" or unknown level; 502 when Wherebox is unreachable.
- `data`: GeoJSON object.
- `places`: list of names/addresses, or `{q, title, description, marker-color, marker-symbol, …}` objects.
- `connect`: `true` for an itinerary line through `places`, with numbered pins.
- `route`: `car`, `bike`, `foot` or `transit` (`true` = car): follow roads through `places` in order instead of straight lines. Routing by FOSSGIS OSRM.
- `routes`, `route_view`: several named routes on one map (a route per day, or alternatives); see the routes example above.
- `legend_title`: heading above the category legend (e.g. `Day`, `Type`). With 2+ categories the legend is interactive: viewers tap a category to show or hide it.
- `directions`: `false` removes the "Directions" button from point popups (default `true`). Also `?directions=0` on the map URL.
- `image`: `true` to render the 1200×630 PNG preview right away and return `image_url`. Off by default: every map still gets a preview at `/m/{id}.png`, rendered the first time something (a link unfurl) fetches it; renders are limited.
- `title`, `description`: plain text. Generated from the data when omitted (e.g. "Prague Castle → Charles Bridge → Old Town Square").
- `basemap`: omit it (default `auto`): `positron` for viewers whose device is in light mode, `dark` in dark mode, switching live; set one only when the style matters or the user asks. Others: `positron` (always light), `liberty` (streets), `bright`, `dark`, `fiord`, `blank` (no map tiles, only your data on a plain light background) `blank-dark` or `blank-auto` (light or dark following the viewer's system setting, switching live). On dark themes `color_by` ramps are flipped (low values dark, high values bright; `rdbu` stays as is). Aliases: `light`, `streets`, `none` (= `blank`).
- `lock`: `true` keeps viewers inside the data's area: panning is limited to around the data and you can't zoom out much past the initial view. Default: `true` on `blank` / `blank-dark` / `blank-auto`, `false` otherwise.
- `color_by`: name of a numeric feature property (e.g. `population`). Features are colored by it in `classes` quantile classes using `palette`, and the legend shows the value ranges (not filterable). Overrides `fill`, `marker-color` and `stroke` of features that have a numeric value; features without one are gray and listed as "No data". `legend_title` sets the legend heading.
- `palette`: `blues` (default), `greens`, `oranges`, `reds`, `purples`, `greys`, `viridis`, `rdbu` (diverging red–blue). Only used with `color_by`.
- `classes`: integer 3–7 (default 5): number of color classes for `color_by`.
- `marker`: `pin` | `circle` | `dot` | `none`. Default: pin up to 300 points, dot above. `circle` is a round marker centered on the point that holds the same icon, emoji or number as a pin.
- `color`: default feature color, hex (`#2563eb`).
- `cluster`: cluster points (default: on above 1000 points). `labels`: draw feature titles as labels.
- `center` `[lng, lat]` and `zoom` (0–22): initial view. Omit to fit all features.

## Response (201)

```json
{
  "id": "k3f9q2xa7b",
  "url": "https://maps.polygrid.dev/m/k3f9q2xa7b",
  "data_url": "https://maps.polygrid.dev/m/k3f9q2xa7b.geojson",
  "title": "Prague Castle → Charles Bridge → Old Town Square",
  "description": "3 places and a 1.6 km route in Prague, Czechia.",
  "alt_text": "Map of Prague, Czechia showing 3 places and a 1.6 km route.",
  "preview_url": "https://maps.polygrid.dev/m/k3f9q2xa7b.png?v=1790000000000",
  "preview_markdown": "[![Map of Prague](…png?v=1790000000000)](https://maps.polygrid.dev/m/k3f9q2xa7b)",
  "markdown": "[Weekend in Prague](https://maps.polygrid.dev/m/k3f9q2xa7b)",
  "embed_html": "<iframe src=\"https://maps.polygrid.dev/m/k3f9q2xa7b?embed=1\" …></iframe>",
  "edit_token": "Qm3x…(22 chars, secret)",
  "edit_url": "https://maps.polygrid.dev/m/k3f9q2xa7b/edit#t=Qm3x…",
  "expires": "Deleted after 30 days without views",
  "feature_count": 4,
  "bbox": [14.4005, 50.0865, 14.4208, 50.0908],
  "warnings": []
}
```

Give the user `url`. Only in chats that really display outside images (not claude.ai, Claude Desktop, Cowork or terminals; when unsure, skip it), start your reply with `preview_markdown` (a thumbnail of the map linking to it): the PNG is rendered lazily on first view, once per map version (`?v=` changes when you update the map), and if rendering is unavailable the image URL serves a generic "Open the map" card instead of an error. Otherwise use `markdown`. With `"image": true` the response also has `image_url` (1200×630 PNG, rendered right away, 5–10 s) and `markdown` becomes the preview image linked to the map; leave it off unless you will show the image (renders are limited). When the request had `route`, `route` is `{"mode","status":"routed","distance_m","duration_s"}` or `{"mode","status":"straight","reason"}`: if straight, tell the user it is not a road route. When the request used `transit` or per-place modes, `route` also has `legs`, `totals` and `mode` (`"mixed"` when legs differ), as in `routes` above. `warnings` lists inputs that were fixed or skipped (swapped lat/lng, unknown basemap, a place that could not be geocoded); mention the relevant ones.

`edit_token` and `edit_url` are only in the create response and are never shown again (only a hash is stored), so keep them. Give viewers `url`, never `edit_url`. Offer `edit_url` to the user only if they want to change the map in the visual editor themselves.

## Update a map (same URL)

`PUT https://maps.polygrid.dev/v1/maps/{id}` with `Authorization: Bearer <edit_token>` and the same body as create replaces the whole map (it is not a merge), keeps the id and URL, and returns the same response without a new token. Viewers see the change immediately.

```bash
curl -X PUT https://maps.polygrid.dev/v1/maps/k3f9q2xa7b -H 'Authorization: Bearer <edit_token>' -H 'Content-Type: application/json' -d '{"title": "Weekend in Prague", "places": ["Prague Castle", "Old Town Square, Prague"], "connect": true}'
```

`GET https://maps.polygrid.dev/v1/plugin` returns the latest version of the create-map skill/plugin and the update commands per client; the bundled skill checks it itself.

To change one thing, `GET https://maps.polygrid.dev/v1/maps/{id}` (public, no token) returns the editable body: `title`, `description`, `basemap`, `lock`, `color_by`, `palette`, `classes`, `marker`, `color`, `cluster`, `labels`, `center`, `zoom`, `legend_title`, `routes` (`[{name, mode, color}]`, no places), `route_view`, `image` and `data` (a FeatureCollection with places already geocoded, routes drawn and areas resolved to polygons; there is no `areas` field, so a PUT does not refetch boundaries). Change what you need and PUT it back; it reproduces the map. Errors: 401 no token, 403 wrong token, 404 unknown or expired map, 429 rate limited (same limit as create). Updating also restarts the 30-day clock.

`edit_url` (`https://maps.polygrid.dev/m/{id}/edit#t=<token>`) opens a simple editor made for non-technical people: they can rename the map and places, change texts, links, photos, category colors and icons, and remove places (no JSON, nothing technical). Layout, basemap, routes and pin positions are locked; for those, change the map yourself with `PUT`. Press "Save changes" to apply. The token is in the `#fragment`, so it is never sent to the server.

If you cannot reach this API (e.g. a sandbox without internet), send the user to the publish page instead: `https://maps.polygrid.dev/new#c=<base64url of the create body as JSON>`. It shows the map for a last look and publishes it on one click ("Publish map"), then shows the share link and the private edit link. Names in `places` are geocoded when the user publishes. Encode with UTF-8 JSON, then base64url (`+` to `-`, `/` to `_`, no `=`).

## Simplestyle cheat sheet (feature `properties`)

| Property | Applies to | Example |
|---|---|---|
| `title` | all | `"Old Town Square"` (popup title, label) |
| `description` | all | plain text popup body; https URLs in it become links |
| `marker-color` | points | `"#e11d48"` |
| `marker-size` | points | `"small"` \| `"medium"` \| `"large"` |
| `marker-symbol` | points | an icon name (below), an emoji (`"☕"`), or 1–3 characters such as a number; overrides the route number |
| `stroke`, `stroke-width`, `stroke-opacity` | lines, polygon outlines | `"#1d4ed8"`, `3`, `0.8` |
| `fill`, `fill-opacity` | polygons | `"#16a34a"`, `0.3` |
| `category` or `group` | all | features without a color get one per category (up to 10) and the map shows a legend that filters (2+ categories) |
| `url` / `website` | all | `"https://example.com/menu"`: a "Website" button in the popup ("Open link" on lines and areas). https only; other schemes are dropped with a warning |
| `address` | all | `"Mariahilfer Str. 10, Vienna"`: popup details, first in the list |
| `phone` | all | `"+43 1 234 5678"`: a tap-to-call link |
| `opening_hours` | all | `"Mo-Fr 8-18, Sa 9-16"`: shown as "Opening hours" |
| `price` | all | `"€€"` or `"from €4"` |
| `rating` | all | `4.6` or `"4.6 (212 reviews)"` |
| `email` | all | `"hello@example.com"`: a mailto link |
| `instagram` | all | `"@handle"` or an https instagram.com URL: a link |
| `image` | all | `"https://example.com/photo.jpg"`: a photo at the top of the popup. https only; hidden if it fails to load |

Pin icons for `marker-symbol` (icon color is automatic: white or dark from `marker-color`; unknown names are dropped with a warning):
restaurant (food, dining), cafe (coffee), bar (pub, beer, drinks), shop (shopping, store), lodging (hotel, hostel), museum (attraction, sight, landmark), park (nature, garden), rail (train, station, metro), airport (plane, flight), hospital (health, doctor, clinic). Aliases in parentheses are accepted too.

Every point popup shows: photo, title, category chip (in the category's color), description, a details list, then buttons: "Website" and "Directions" (opens the user's maps app at the point; lines and areas get none). The details list is built from the other properties (address, phone, price, rating, hours first, then the rest; keys like `known_for` become "Known for"; long text is shortened with "More"; internal keys such as marker-*, stroke*, fill*, ids are hidden). So fill in as many real details as you can find: address, website/url, image, opening_hours, price and a "Known for"-style field. Use only facts from real sources; never invent details. Set `"directions": false` to remove the Directions button.

## Data maps (choropleth / blind maps)

Use this when the point is a number per area: districts by population, regions by income, countries by a score. Use real data only: numbers the user gave you or that you sourced; never invent values.

**1. `areas` (shapes for free).** Name the region and the API draws the real boundaries; you only send the numbers. `color_by` defaults to `"value"` when `values` has numbers, and `color_by: "population"` or `"area_km2"` works with no data at all. Pick `palette` to fit the data (`rdbu` for values above and below a midpoint, otherwise a sequential one) and set `legend_title` as "Name (unit)", e.g. `"Unemployment (%)"`: the popup then shows "Unemployment  4.3 %" as its first row. A unit-only title like `"%"` works too (the metric name is taken from the map title), but a name is clearer. Popups already turn keys like `median_income` into "Median income" and format numbers; for exact labels add `property_labels`, e.g. `{"value": "Unemployment rate", "median_income": "Median income (€)"}`.

```json
{"areas": {"within": "Czechia"}, "color_by": "population", "palette": "viridis", "legend_title": "Population"}
```

```json
{
  "areas": {"within": "Berlin", "values": {"Mitte": 12.1, "Pankow": 8.4, "Neukölln": 15.3}},
  "title": "Unemployment by district",
  "legend_title": "Unemployment (%)"
}
```

**2. Your own GeoJSON.** When you already have the polygons (or they are not administrative areas), put the number in each feature's properties, set `"color_by"` to its name and use `"basemap": "blank"` (or `blank-dark`, `blank-auto`). Features without a numeric value are gray and listed as "No data". In the viewer, hovering an area highlights its outline and clicking selects it and opens its popup with the properties. On blank basemaps polygons are drawn opaque with thin borders.

```json
{
  "title": "Berlin districts by population",
  "basemap": "blank",
  "color_by": "population",
  "palette": "blues",
  "legend_title": "Residents",
  "data": {"type": "FeatureCollection", "features": [
    {"type": "Feature", "properties": {"title": "Mitte", "population": 397134},
     "geometry": {"type": "Polygon", "coordinates": [[[13.34, 52.51], [13.42, 52.51], [13.42, 52.55], [13.34, 52.55], [13.34, 52.51]]]}}
  ]}
}
```

## Viewer URL parameters

Append to `url` to change the display without creating a new map: `?basemap=dark&marker=dot&color=e11d48&cluster=1&labels=1`. `embed=1` hides the title panel (for iframes). Other files per map: `/m/{id}.geojson` (normalized data), `/m/{id}.png` (1200×630 preview for every map, rendered on first request; used for link previews in chat apps), `/oembed?url=…` (oEmbed).

## Limits

- Maps are deleted after 30 days without views. Each view or update restarts the clock.
- Request body up to 2 MB. Up to 50 places per request.
- 60 creates per minute per IP.
- Maps can be updated with the edit token (above) but not deleted; they expire on their own.

## Errors

Errors are JSON `{"error": "…", "hint": "…", "example": {…}}`. `hint` says how to fix the call and `example` is a minimal valid request. Codes: 400 invalid input, 401 missing edit token, 403 wrong edit token, 404 unknown or expired map, 413 body too large, 429 rate limited (see `Retry-After`), 503 preview image temporarily unavailable.

## MCP

Remote MCP server (streamable HTTP, no auth): `https://maps.polygrid.dev/mcp`. Three tools:

- `create_map`: same input as `POST /v1/maps`. Result has `url`, plus `edit_url` and `edit_token` (owner-only secrets; keep them for update_map, never show them to viewers).
- `get_map` `{id}`: public read. `id` is the map id or any map link. Returns url, GeoJSON/PNG/embed links and the editable `body` (as `GET /v1/maps/{id}`).
- `update_map` `{id, edit_token?, changes | body}`: changes the map in place, same URL. `changes` is a partial body shallow-merged onto the current one (e.g. `{"basemap":"dark"}`; a key set to null is removed), `body` is a full replacement. `id` may be the edit URL (`…/edit#t=TOKEN`), which supplies the token. Wrong or missing token returns an error that says to ask the user for the edit link. Same rate limit as create.

In chat apps that support MCP Apps (Claude, VS Code, …) the three tools show the map inline (interactive, with an "Open map" link); other clients get text and `structuredContent` only.

Claude Code: `claude mcp add --transport http polygrid-maps https://maps.polygrid.dev/mcp`

## More

- [OpenAPI spec](https://maps.polygrid.dev/openapi.json)
- [Human docs](https://maps.polygrid.dev/docs)

## Agent plugins

Install guides for Claude Code, Codex, Cursor, claude.ai / Claude Desktop, Gemini CLI, VS Code and other MCP clients: https://maps.polygrid.dev/docs/agents

Copy-and-paste example prompts (trips, routes, places to share, data maps, editing, embedding and exporting a map): https://maps.polygrid.dev/docs/agents/prompts

- Claude Code: `claude plugin marketplace add agilek/polygrid-maps` then `claude plugin install polygrid-maps@polygrid`
- Codex: `codex plugin marketplace add agilek/polygrid-maps` then `codex plugin add polygrid-maps@polygrid`
- Gemini CLI: `gemini extensions install https://github.com/agilek/polygrid-maps`
- Skill only, any agent: `npx -y skills add agilek/polygrid-maps --skill create-map`
- claude.ai / Claude Desktop: add the custom connector `https://maps.polygrid.dev/mcp`, or upload the skill zip https://maps.polygrid.dev/create-map.zip
