On this page
Polygrid Maps API
POST GeoJSON or place names, get a shareable map link.
Polygrid Maps turns a single HTTP request into a hosted map page and a Markdown snippet you can paste into a chat, plus a PNG preview when you ask for one. It exists so AI agents can answer "show me on a map" with a link instead of a list of coordinates.
- No API key. No account, no signup. Creation is rate limited per IP.
- Maps expire. A map is deleted 30 days after its last view or update. Every view resets the clock.
- Editable. The create response carries a secret
edit_tokenand anedit_url(a simple visual editor for non-technical users).PUTa new body to change the map on the same link. - One request, every format. A viewer URL, a Markdown link, an iframe embed and the normalized GeoJSON. Add
"image": truefor a 1200×630 PNG preview. - Built for AI agents. An MCP server,
/llms.txt,/openapi.json, place-name geocoding, and errors that say how to fix the request.
Base URL: https://maps.polygrid.dev. Requests and responses are JSON. CORS is open, so browsers can call it directly.
Maps are create-only: there is no edit, delete or list endpoint. There are no private maps; anyone with the link can open one. route follows roads between places, but there are no turn-by-turn directions.
Quickstart
Send GeoJSON to POST /v1/maps. Coordinates are [longitude, latitude].
curl -X POST https://maps.polygrid.dev/v1/maps \
-H "Content-Type: application/json" \
-d '{
"title": "Coffee in Prague",
"data": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": { "type": "Point", "coordinates": [14.4189, 50.0819] },
"properties": { "title": "Café Louvre", "marker-color": "#e11d48" }
},
{
"type": "Feature",
"geometry": { "type": "Point", "coordinates": [14.4068, 50.0798] },
"properties": { "title": "Café Savoy" }
}
]
}
}'const res = await fetch("https://maps.polygrid.dev/v1/maps", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
title: "Coffee in Prague",
data: {
type: "FeatureCollection",
features: [
{
type: "Feature",
geometry: { type: "Point", coordinates: [14.4189, 50.0819] },
properties: { title: "Café Louvre", "marker-color": "#e11d48" },
},
{
type: "Feature",
geometry: { type: "Point", coordinates: [14.4068, 50.0798] },
properties: { title: "Café Savoy" },
},
],
},
}),
});
const map = await res.json();
console.log(map.url); // https://maps.polygrid.dev/m/k3f9q2xa7bimport requests
res = requests.post("https://maps.polygrid.dev/v1/maps", json={
"title": "Coffee in Prague",
"data": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [14.4189, 50.0819]},
"properties": {"title": "Café Louvre", "marker-color": "#e11d48"},
},
{
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [14.4068, 50.0798]},
"properties": {"title": "Café Savoy"},
},
],
},
})
m = res.json()
print(m["url"]) # https://maps.polygrid.dev/m/k3f9q2xa7bThe API answers 201 Created:
{
"id": "k3f9q2xa7b",
"url": "https://maps.polygrid.dev/m/k3f9q2xa7b",
"data_url": "https://maps.polygrid.dev/m/k3f9q2xa7b.geojson",
"title": "Coffee in Prague",
"description": "2 places in Prague, Czechia.",
"alt_text": "Map of Prague, Czechia showing 2 places.",
"preview_url": "https://maps.polygrid.dev/m/k3f9q2xa7b.png?v=1790000000000",
"preview_markdown": "[](https://maps.polygrid.dev/m/k3f9q2xa7b)",
"markdown": "[Coffee in Prague](https://maps.polygrid.dev/m/k3f9q2xa7b)",
"embed_html": "<iframe src=\"https://maps.polygrid.dev/m/k3f9q2xa7b?embed=1\" width=\"100%\" height=\"450\" style=\"border:0\" loading=\"lazy\" title=\"Coffee in Prague\"></iframe>",
"edit_token": "Qm3x…",
"edit_url": "https://maps.polygrid.dev/m/k3f9q2xa7b/edit#t=Qm3x…",
"expires": "Deleted after 30 days without views",
"feature_count": 2,
"bbox": [14.4068, 50.0798, 14.4189, 50.0819],
"warnings": []
}Open url in a browser, or post markdown in a chat. With "image": true, the response also has image_url and markdown becomes the preview image linked to the map.
Create a map
POST https://maps.polygrid.dev/v1/maps with a JSON body. Send data, places, areas, or a mix. Every other field is optional. The MCP tool create_map takes the same fields.
| Field | Type | Default | Description |
|---|---|---|---|
data | GeoJSON object | — | Geometry, Feature, FeatureCollection or GeometryCollection. Required unless places or areas is set. See Geometry & styling. |
areas | object | — | Draws real administrative boundaries from Wherebox, no GeoJSON needed. {within, level?, values?}: within is an area name ("Berlin", "Praha, Czechia") or a Wherebox id ("osm:r62422"); level is "auto" (default: the first level with 2+ parts), an OSM admin level 2–11 or "none"; values maps area names or ids to a number (property value) or an object of properties. Defaults to a locked blank basemap with labels. See Data maps. |
places | array of strings or objects | — | Up to 50 place names to geocode into points. Required unless data or areas is set. See Places & geocoding. |
connect | boolean | false | Draw a line through places in order and number the pins 1, 2, 3. |
route | string | — | Follow roads through places in order instead of straight lines: car, bike, foot or transit. Adds distance and travel time and numbers the pins. See Routes. |
routes | array of objects | — | Several named routes on one map, for example a route per day. Each {name, mode, places, color?, remove?}. Max 6 routes. See Several routes. |
route_view | string | generated | tabs (one route at a time) or together (all visible). Default tabs with 2+ named routes. See Several routes. |
image | boolean | false | Also render a 1200×630 PNG preview (image_url) for chat replies and link previews. Rendering starts right away and takes 5–10 s; renders are limited, so only ask when you'll show the image. See PNG preview. |
title | string | generated | Map title for the page, the link preview and the alt text. |
description | string | generated | One-line summary shown under the title and in link previews. |
basemap | string | auto | auto (positron on light devices, dark on dark ones), liberty, bright, positron, dark, fiord, blank, blank-dark or blank-auto (follows the viewer's light/dark setting). Aliases: light → positron, streets → liberty, none → blank. See Basemaps. |
lock | boolean | true on blank, else false | Keep viewers inside the data's area: panning is limited to around the data and you can't zoom out much past the initial view. |
color_by | string | — | Name of a numeric feature property, such as 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; write it as "Name (unit)", e.g. Unemployment (%), and popups label the value "Unemployment" and show "4.3 %". See Data maps. |
property_labels | object | — | Exact popup labels per property key, e.g. {"value": "Unemployment rate", "median_income": "Median income (€)"}. Optional: without it keys such as median_income show as "Median income", numbers are grouped and units (_km2, _pct, _eur) are appended. Returned by GET /v1/maps/{id}. |
palette | string | blues | blues, greens, oranges, reds, purples, greys, viridis or rdbu (diverging red–blue). Only used with color_by. On dark themes the ramp is flipped so low values sit dark and high values are bright (rdbu is never flipped). |
classes | integer | 5 | Number of color classes for color_by, 3 to 7. |
marker | string | by point count | pin, circle, dot or none. circle is a round marker centered on the point that holds the same icon, emoji or number as a pin. none hides points and keeps lines and areas. |
color | string | #2563eb | Color for every feature that has no color of its own: hex (#e11d48, e11d48, #e14) or a basic name like red. |
cluster | boolean | by point count | Group nearby points into numbered bubbles that split as you zoom in. |
directions | boolean | true | A "Directions" button in point popups opens the user's maps app (Apple Maps on iPhone and iPad, Google Maps elsewhere) with the point as destination. false removes it. Lines and areas never have one. Also ?directions=0 on the map URL. |
labels | boolean | false | Draw each feature's title as a text label on the map. |
center | [lng, lat] | fit to data | Initial map center. Longitude first, as in GeoJSON. |
zoom | number | fit to data | Initial zoom level, for example 12 for a city. Use with center. |
Unknown basemap or marker values don't fail the request. The API uses the default and adds an entry to warnings.
Smart defaults
Leave a field out and the API picks a value from the data:
- Marker style. Up to 300 points render as
pinmarkers that can hold an emoji or a number. Above 300, points render asdot, a GPU circle layer that stays responsive with tens of thousands of points. - Clustering. Turns on above 1,000 points. Send
"cluster": falseto draw every point. - Title. One to three named features give
"A, B & C". Aconnectroute gives"A → B → C"for up to 4 stops, then"Route with 7 stops in Vienna, Austria". More features give"12 places in Vienna, Austria". Unnamed features give"Map of Vienna, Austria". - Description. Counts per kind, the total line length and the area:
"12 places and a 4.3 km route in Vienna, Austria." - Alt text.
"Map of Vienna, Austria showing 12 places and a 4.3 km route."Used inalt_text,markdownand the page'sog:image:alt.
The area name comes from the geocoded places, or from one reverse geocode of the center of your data. Maps under 50 km across get a city, under 500 km a region, larger maps a country, and maps over 3,000 km across no area name. A map that spans several countries is named after the one at its center, so set title when that matters.
Geometry & styling
data takes any RFC 7946 GeoJSON object:
| Type | Draws as |
|---|---|
Point, MultiPoint | Pins or dots |
LineString, MultiLineString | Lines. The popup shows the length. |
Polygon, MultiPolygon | Filled areas with an outline. Holes are supported. |
GeometryCollection | Each member by its type |
Feature, FeatureCollection | Their geometries, styled by their properties |
Coordinates are [longitude, latitude] in WGS 84. If your coordinates look like [latitude, longitude], the API swaps them and adds a warning. Don't rely on the guess: near the equator both orders are valid numbers.
Feature properties
Style individual features with simplestyle-spec properties. Features without them use the request's color.
| Property | Applies to | Example | Effect |
|---|---|---|---|
title | all | "Café Louvre" | Popup heading, and the label when labels is on |
description | all | "Open 8–22" | Popup text; https URLs in it become links |
marker-color | points | "#e11d48" | Pin or dot color |
url, website | all | "https://example.com/menu" | "Website" button in the popup ("Open link" on lines and areas; https only) |
address | all | "Mariahilfer Str. 10, Vienna" | Popup details, first in the list |
phone | all | "+43 1 234 5678" | Tap-to-call link |
opening_hours | all | "Mo-Fr 8-18, Sa 9-16" | Shown as "Opening hours" |
price, rating | all | "€€", 4.6 | Popup details |
email, instagram | all | "hi@example.com", "@handle" | mailto link; link to the Instagram profile |
image | all | "https://example.com/photo.jpg" | Photo at the top of the popup (https only; hidden if it fails to load) |
marker-size | points | "small", "medium", "large" | Pin size |
marker-symbol | points | "cafe", "☕", "3" | Shown inside the pin or circle: one of the pin icons, an emoji, or 1–3 characters such as a number. Overrides the route number. |
stroke | lines, outlines | "#0f766e" | Line color |
stroke-width | lines, outlines | 3 | Line width in pixels |
stroke-opacity | lines, outlines | 0.8 | 0 to 1 |
fill | polygons | "#14b8a6" | Area color |
fill-opacity | polygons | 0.3 | 0 to 1 |
A point popup is a card: photo, title, category chip in the category's color, description, a details list and buttons. The details list shows every other property with a readable label (opening_hours becomes "Opening hours"; keys written in Title Case stay as written), starting with address, phone, price, rating and opening hours. Phone numbers, emails, https URLs and Instagram handles become links, long text is shortened with "More", and internal keys (marker-*, stroke*, fill*, ids) are hidden. Add as many real details as you can source: address, website, photo, opening hours, price and a "Known for" style field.
Pin icons
Set marker-symbol to an icon name to draw an icon inside the pin. There are 10, covering the usual map needs. The icon's color isn't configurable: it's white or dark, whichever reads better on the pin's marker-color. The aliases are converted to the icon name; any other unknown name is dropped with a warning, and the pin stays plain (or keeps its route number).
{ "q": "Hotel Josef, Prague", "marker-symbol": "lodging", "marker-color": "#7c3aed" }| Icon | marker-symbol | Also accepted |
|---|---|---|
restaurant | food, dining, eat | |
cafe | coffee, café | |
bar | pub, beer, drinks, nightlife | |
shop | shopping, store, market | |
lodging | hotel, accommodation, hostel, bed | |
museum | attraction, sight, sightseeing, landmark, culture | |
park | nature, garden, tree | |
rail | train, station, transit, metro | |
airport | plane, flight | |
hospital | health, doctor, clinic, medical |
Icons are drawn on pin and circle markers. With marker: "dot" or clustering, points are plain dots. Icons are Maki (CC0).
Category colors and legend
Give features a category (or group) property and leave out the colors. Each category gets its own color from a 10-color palette, and the viewer shows a legend. With two or more categories the legend filters the map: viewers tap a category to hide or show it. legend_title names the legend.
{
"data": {
"type": "FeatureCollection",
"features": [
{ "type": "Feature", "properties": { "title": "Lido", "category": "Swim" },
"geometry": { "type": "Point", "coordinates": [14.4168, 50.0590] } },
{ "type": "Feature", "properties": { "title": "Letná", "category": "Park" },
"geometry": { "type": "Point", "coordinates": [14.4220, 50.0960] } }
]
}
}A feature with its own marker-color, stroke or fill keeps it. Up to 10 categories get palette colors.
Places & geocoding
Send place names instead of coordinates. Each entry in places is a string, or an object with the search text in q plus any simplestyle properties for that point.
curl -X POST https://maps.polygrid.dev/v1/maps \
-H "Content-Type: application/json" \
-d '{
"places": [
"Prague Castle",
{ "q": "Charles Bridge, Prague", "title": "Bridge", "marker-color": "#e11d48" },
"Old Town Square, Prague"
],
"connect": true
}'With "connect": true, the map draws a straight line through the places in order, numbers the pins 1, 2, 3, and puts the route length in the description:
{
"title": "Prague Castle → Bridge → Old Town Square",
"description": "3 places and a 2.1 km route in Prague, Czechia.",
"feature_count": 4,
"warnings": []
}- Geocoder. Photon, which searches OpenStreetMap data. The first result wins.
- Be specific. Add the city or country.
"Paris"finds Paris, France;"Paris, Texas"finds the other one. - Limit. 50 places per request, geocoded in parallel. For more points, send coordinates in
data. - Not found. A place that returns no result is skipped and listed in
warnings. The request fails with400only when nothing is left to draw. - Mixing.
placesanddatacan go in one request. The geocoded points are added to your GeoJSON.
Routes
Set route to follow roads instead of drawing straight lines. The places become stops, in order:
curl -X POST https://maps.polygrid.dev/v1/maps \
-H "Content-Type: application/json" \
-d '{ "places": ["Prague", "Bratislava"], "route": "car" }'{
"title": "Prague → Bratislava",
"description": "2 places and a 335 km drive (about 3 h 36 min).",
"warnings": []
}- Modes.
car,bike,footortransit. Aliasesdriving,cycling,walkingand, for transit,public_transport,metro,subway,bus,tram,trainwork too, andtruemeanscar. An unknown mode is a400that lists them.transitis not routed: see Several routes. - Router. OSRM run by FOSSGIS on OpenStreetMap data. One request per map. The route popup shows its length and travel time.
- Fallback. If the mode is unknown, the router is down, or a place is more than 5 km from a road (another continent, open sea), the map draws straight lines and says why in
warnings. The map is still created. - Estimates. Distance and time are for an overview map: no live traffic, no turn-by-turn directions.
Several routes on one map
Use routes for a trip with a route per day, or for alternatives to compare. One map, one link:
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"
}'{
"routes": [
{ "name": "Day 1", "mode": "foot", "color": "#2563eb", "status": "routed", "distance_m": 4200, "duration_s": 3100, "stops": 2 },
{ "name": "Day 2", "mode": "foot", "color": "#e11d48", "status": "routed", "distance_m": 1300, "duration_s": 960, "stops": 2 }
]
}- Route fields.
name(up to 60 characters, unique; required with 2+ routes),mode(car,bike,footortransit, defaultfoot),places(same forms as top-levelplaces),color(optional; an auto palette is used otherwise),remove(truedeletes the route). Stops are numbered 1, 2, 3 per route. Each route falls back to straight lines on its own, with areasonin the response. - Per-leg modes. A place in
placesmay be an object withmode: the mode of the leg arriving at that place. It overrides the route'smodefor that one leg (modeon the first place is ignored). 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. A
transitleg is drawn as a dashed straight line with a 🚇 badge, with no times. 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 form a run. Each car, bike or foot run is one OSRM request through its stops; each transit leg is its own line and never goes to OSRM. At most 15 routed runs per request, otherwise
400(merge legs, use fewer routes, or add routes in a later update). - Limits. Up to 6 routes per map, 2–25 places per route, 50 places per request in total (top-level
placesplus all routes). - View.
route_view: "tabs"shows one route at a time with tabs (All, Day 1, Day 2), good for the days of a trip."together"shows every route, and the legend toggles each one: good for comparing alternatives, such as three bike route options. The default istabswith 2+ named routes. On the map URL,?route=2,?route=Day%202or?route=allopens a route, and?route_view=togetheroverrides the mode. - Shared features. Top-level
places,dataandareascan be combined withroutes. They are shown with every route. - Add routes to an existing map.
PUTtheGETbody withroutesappended, or call the MCP toolupdate_mapwithchanges: {"routes": [ …new routes only… ]}. Existing routes and features are kept. A route given withplacesreplaces the route of the same name.{"name": "Day 1", "remove": true}deletes one. Withoutplaces,{"name": "Day 1", "color": "#e11d48"}recolors it and a differentmodere-routes it from its stops. To switch a whole route to driving, send{"name": "Day 1", "mode": "car"}(PUTorupdate_map) with noplaces: every leg gets that mode (also fromtransit), per-place modes are replaced, nothing is re-geocoded and the link stays the same. An unknown name withoutplacesis a400. - Single route.
routeandconnectstill work as before for one route throughplaces.
Response
A successful create returns 201 with these fields:
| Field | Type | Description |
|---|---|---|
id | string | 10-character map ID, for example k3f9q2xa7b. |
url | string | The map page. This is the link to give the user. |
image_url | string? | 1200×630 PNG preview. Only present with "image": true. See PNG preview. |
data_url | string | The normalized GeoJSON FeatureCollection. See Raw GeoJSON. |
title | string | Your title, or the generated one. |
description | string | Your description, or the generated one. |
alt_text | string | Alt text for the preview image. |
preview_url | string | The PNG preview with ?v= set to the update time, so an edited map shows a fresh image. Rendered lazily on first fetch, once per map version. |
preview_markdown | string | [](url): a thumbnail linking to the map. Start your reply with it where your chat shows images. If rendering is unavailable the image shows a generic "Open the map" card instead of failing. |
markdown | string | A link to the map, [title](url). With "image": true it's the preview image linked to the map, [](url), which renders in GitHub, Slack, Discord and most chat UIs. |
route | object? | Present when the request had route. Either {"mode":"foot","status":"routed","distance_m":2213,"duration_s":1800} (with legs, totals and "mixed" when transit or per-place modes were used), or {"mode":"car","status":"straight","reason":"…"} when no road route was found and straight lines were drawn. See Routes. |
routes | array? | Present when the map has routes: [{name, mode, color, status, distance_m, duration_s?, stops, legs, totals, reason?}]. status is routed or straight. mode is the single mode, or "mixed" when legs differ. legs is [{from, to, mode, status, distance_m?, duration_s?}] in order; totals is per mode, e.g. {"foot": {"distance_m": 3200, "duration_s": 2700}, "transit": {"legs": 2}}. distance_m and duration_s sum car, bike and foot legs only. See Several routes. |
embed_html | string | An <iframe> of the map with ?embed=1. |
edit_token | string | Secret for PUT /v1/maps/{id} (Authorization: Bearer). Only in the create response, never shown again: only a hash is stored. Keep it private. |
edit_url | string | Link to the visual editor for this map, …/m/{id}/edit#t=<token>. The token is in the fragment, so it never reaches the server. Give it only to the map's owner. |
expires | string | The lifetime rule in words: "Deleted after 30 days without views". |
feature_count | number | Features on the map, including geocoded places and the connect line. |
bbox | [w, s, e, n] | Bounding box of all features: west, south, east, north. |
warnings | string[] | Fixes the API made to your input. Empty when nothing needed fixing. See Warnings. |
Viewer URL parameters
The map page at https://maps.polygrid.dev/m/:id takes query parameters that override the display settings for that link only. The stored map doesn't change, so one map can be shared in several styles without creating it again.
| Parameter | Values | Example |
|---|---|---|
basemap | a basemap name or alias | ?basemap=dark |
marker | pin, circle, dot, none | ?marker=circle |
color | hex color, # encoded as %23 | ?color=%23e11d48 |
cluster | 1 or 0 | ?cluster=1 |
labels | 1 or 0 | ?labels=1 |
embed | 1 | ?embed=1 hides the title panel, for iframes |
Combine them with &:
https://maps.polygrid.dev/m/k3f9q2xa7b?basemap=dark&marker=dot&color=%2357e89a
https://maps.polygrid.dev/m/k3f9q2xa7b?basemap=liberty&labels=1
https://maps.polygrid.dev/m/k3f9q2xa7b?embed=1The PNG preview always uses the settings stored at creation.
Basemaps
All basemaps are OpenFreeMap vector styles.
| Name | Look | Aliases |
|---|---|---|
auto | The default. positron for viewers whose device is in light mode and dark for dark mode, switching live without a reload. The title panel, legend, popups and color_by ramps follow. PNG previews and link unfurls are always light. | — |
positron | Light grey and quiet, so your data stands out. Always light. | light, default |
liberty | Full-color street map with buildings and land use. | streets |
bright | Street map with saturated road and water colors. | — |
dark | Dark grey. Use light marker colors. | — |
fiord | Dark blue-grey. | — |
blank | No map tiles: only your data on a plain light background. For editorial, choropleth and blind maps. lock defaults to on. | none |
blank-dark | The same on a dark background. | — |
blank-auto | Light or dark, following the viewer's system setting (switches live). | — |
Data maps (choropleth)
Use these when the point is a number per area, such as districts by population. Use real numbers only, never invented ones.
areas: shapes for free. Name a region and the API draws its real boundaries from Wherebox (data © OpenStreetMap contributors and Overture Maps Foundation, credited automatically in the map attribution). You only send the numbers.
within: 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:"auto"(default: the first level with 2+ parts, so Berlin gives 12 districts, Czechia 14 regions, Praha 57 districts), an OSM admin level 2–11, or"none"for just the outline.values: an object keyed by area name or id. A number becomes the propertyvalueandcolor_bydefaults 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"finds"Friedrichshain-Kreuzberg"). Unmatched keys produce a warning listing the area names.- Every area has
title,population,area_km2(and a hiddenarea_id), so"color_by": "population"works without any data. - Defaults:
blankbasemap with lock, labels on (up to 60 areas), title "<Area> by <color_by>" or the area name.areascan be combined withdataandplaces; pins and lines are drawn on top. GET /v1/maps/{id}returns the resolved polygons indata(noareasfield), so aPUTdoes not refetch. Errors:400"No area named …" or unknown level,502when Wherebox is unreachable.
{"areas": {"within": "Czechia"}, "color_by": "population",
"palette": "viridis", "legend_title": "Population"}{"areas": {"within": "Berlin", "values": {"Mitte": 12.1, "Pankow": 8.4, "Neukölln": 15.3}},
"title": "Unemployment by district (%)", "legend_title": "%"}Your own GeoJSON. When you already have polygons, put the number in each feature's properties, name it in color_by and use a blank basemap (or blank-dark, blank-auto) so only your data shows. Features without a numeric value are gray and listed as "No data" in the legend. In the viewer, hovering an area highlights its outline; clicking selects it and opens a popup with its properties. On blank basemaps polygons are drawn opaque with thin borders, like an editorial map.
{"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]]]}}
]}}MCP server
Agents that speak the Model Context Protocol can create maps without writing HTTP calls.
Use it from your AI agent: step-by-step install guides for Claude Code, Codex, Cursor, Claude, Gemini CLI and VS Code, with plugins and the skill, are in Agents, with copy-and-paste example prompts.
- Endpoint:
https://maps.polygrid.dev/mcp - Transport: Streamable HTTP. No auth.
- Tool:
create_map. Takes the same input asPOST /v1/mapsand returns the same fields as the response.
claude mcp add --transport http polygrid-maps https://maps.polygrid.dev/mcp- Open Settings → Connectors and choose Add custom connector.
- Name it
Polygrid Mapsand paste the URL below. Leave the OAuth fields empty.
https://maps.polygrid.dev/mcpAdd to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:
{
"mcpServers": {
"polygrid-maps": { "url": "https://maps.polygrid.dev/mcp" }
}
}Add to .vscode/mcp.json:
{
"servers": {
"polygrid-maps": { "type": "http", "url": "https://maps.polygrid.dev/mcp" }
}
}Most clients that support remote servers take a url entry:
{
"mcpServers": {
"polygrid-maps": { "url": "https://maps.polygrid.dev/mcp" }
}
}Clients that only run local stdio servers can bridge with mcp-remote:
{
"mcpServers": {
"polygrid-maps": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://maps.polygrid.dev/mcp"]
}
}
}Then ask for a map in plain words, for example: "Map my Prague weekend: Prague Castle, Charles Bridge, Old Town Square, in that order." The agent calls create_map with places and connect: true and replies with the link.
For AI agents
To connect an agent to Polygrid Maps (plugin, MCP server or skill), see Use it from your AI agent. Two machine-readable entry points:
https://maps.polygrid.dev/llms.txtis this documentation as Markdown.https://maps.polygrid.dev/serves the same file.https://maps.polygrid.dev/openapi.jsonis the OpenAPI schema, generated from the same validation code the API runs.
How to answer the user
- Put the share link (
url) first, on its own line, then one line about what the map shows, then anywarningsin plain words. - Start with
preview_markdownonly where your chat really displays outside images (not claude.ai, Claude Desktop, Cowork or terminals; when unsure, skip it). - 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.
- Offer
edit_urlas "your private edit link (lets you change the map later; don't share it)". Never show the rawedit_tokenin chat; keep it for your ownPUT/update_mapcalls. - No technical narration: no APIs, tokens, proxies, plugins, JSON or which tool you used.
- If the API is unreachable from your environment, don't explain why. Give the user the
https://maps.polygrid.dev/new#c=…publish link and say "Your map is ready, open this link and press Publish map". - Mention that tapping a place shows its details, and suggest one or two tweaks.
Tips
- Use
placesinstead of guessing coordinates. The geocoder knows where Charles Bridge is. A model recalling coordinates from memory can be off by a few kilometres. - Fill popups with real details. Address, website, photo, opening hours, price, a "Known for" field: only from real sources.
- Give the user the
url. In chats that show images, start withpreview_markdown(the map thumbnail); otherwise post themarkdownfield. Ask for"image": trueonly when you'll show the preview image. - Check
route.status. If it'sstraight, tell the user the line is not a road route and why (route.reason). - Read
warnings. Tell the user when a place wasn't found or a value was replaced. - Set
titlewhen you know the intent. Generated titles describe the data ("3 places in Lisbon, Portugal"). "Shortlist for Saturday dinner" is more useful. - Change the look with URL parameters. To show the same map on a dark basemap, append
?basemap=darktourlinstead of creating a new map. - Mention that it expires. Maps without views for 30 days are deleted. Don't store the link as a permanent record.
- Change a map with
PUT, not a new map. Keep theedit_token,GETthe body, change it andPUTit back: the link the user already has stays valid.
Update a map
PUT https://maps.polygrid.dev/v1/maps/{id} with Authorization: Bearer <edit_token> and the same body as create replaces the map's content (a full replace, not a merge). The id and link stay the same, the response is the create response without a new token, and the 30-day clock restarts.
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/maps/{id} is public and returns the editable body: title, description, basemap, lock, color_by, palette, classes, marker, color, cluster, labels, center, zoom, legend_title, image and data (a FeatureCollection, places already geocoded and areas resolved to polygons; there is no areas field, so a PUT does not refetch boundaries). Change a field and PUT it back to reproduce the map with your edit. 401 means no token, 403 a wrong one, 404 an unknown or expired map.
For people, open edit_url: a simple editor (no JSON, nothing technical) lets them rename the map and places, change texts, links, photos, category colors and icons, or remove places. Basemap, layout, routes and pin positions are locked. Save changes applies the edit.
No network access from where the map is built? Send the user to https://maps.polygrid.dev/new#c=<base64url JSON>, with the create body as UTF-8 JSON in base64url. The page previews the map and publishes it on one click (places are geocoded then), and shows the share link and the private edit link.
Links, photos and the filtering legend
Feature properties url (an "Open link" button) and image (a photo at the top of the popup) accept https:// URLs only; anything else is dropped with a warning. https URLs inside description become links. With two or more category values the legend becomes a set of toggle buttons with counts and a "Show all" button; legend_title sets the heading above them.
Errors & warnings
Errors return a JSON body with three fields. error says what went wrong, hint says how to fix it, and example is a minimal valid request body.
{
"error": "Request needs data or places",
"hint": "Send GeoJSON in data, or a list of place names in places.",
"example": { "places": ["Prague Castle", "Charles Bridge, Prague"] }
}The wording of error and hint can change. Branch on the HTTP status.
| Status | Meaning | What to do |
|---|---|---|
400 | Invalid input: malformed JSON, invalid GeoJSON, or nothing left to draw after geocoding. With areas: no area with that name, or an unknown level. | Read hint, fix the body, retry. |
401 / 403 | On PUT: the edit token is missing (401) or wrong (403). | Send Authorization: Bearer <edit_token> from the create response. |
404 | The map doesn't exist or has expired. | Create it again. |
413 | Request body is larger than 2 MB. | Simplify geometry or drop unused properties. |
429 | More than 60 maps created in a minute from your IP. | Wait for the Retry-After seconds. |
503 | PNG preview temporarily unavailable. | Retry after Retry-After. Use url meanwhile. |
Warnings
Warnings are fixes the API made so the request could still succeed. The map is created; warnings says what changed:
"warnings": [
"Coordinates looked like [latitude, longitude]; swapped them. GeoJSON order is [longitude, latitude].",
"Unknown basemap \"satellite\"; using auto. Valid: auto, liberty, bright, positron, dark, fiord, blank, blank-dark, blank-auto.",
"Could not geocode place \"Elbonia\"; skipped it. Add the city/country or pass coordinates in `data`."
]Other fixes that produce a warning: a bare GeoJSON body (treated as {"data": …}), unclosed polygon rings (closed for you), features with a null geometry (skipped), unknown fields, colors or marker styles (ignored), and more than 10 categories (not auto-colored).
Limits & data lifetime
| Limit | Value |
|---|---|
| Map lifetime | Deleted 30 days after the last view of the page, PNG or GeoJSON, or the last update. Maps can't be deleted sooner. |
| Request body | 2 MB |
| Places per request | 50 |
| Rate limit | 60 map creations or updates per minute per IP, REST and MCP combined |
| PNG renders | Daily budget; 503 with Retry-After when it runs out |
Map pages are not cached at the edge, so an update shows up for every viewer immediately. GeoJSON, PNGs and oEmbed are cached for up to 60 seconds. Every request counts as a view.
Anyone with a map's URL can open it. IDs are 10 random characters and can't be guessed, but don't put data in a map that you wouldn't share.
Data attribution
Map data © OpenStreetMap contributors. Basemap tiles by OpenFreeMap, using the OpenMapTiles schema. Geocoding by Photon. Routing by FOSSGIS OSRM. Rendering by MapLibre GL JS. The map page shows the attribution on every map; keep it visible when you embed one.