View as Markdown
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_token and an edit_url (a simple visual editor for non-technical users). PUT a 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": true for 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.

What it doesn't do

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" }
        }
      ]
    }
  }'

The 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": "[![Map of Prague, Czechia showing 2 places.](https://maps.polygrid.dev/m/k3f9q2xa7b.png?v=1790000000000)](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.

FieldTypeDefaultDescription
dataGeoJSON object—Geometry, Feature, FeatureCollection or GeometryCollection. Required unless places or areas is set. See Geometry & styling.
areasobject—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.
placesarray of strings or objects—Up to 50 place names to geocode into points. Required unless data or areas is set. See Places & geocoding.
connectbooleanfalseDraw a line through places in order and number the pins 1, 2, 3.
routestring—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.
routesarray 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_viewstringgeneratedtabs (one route at a time) or together (all visible). Default tabs with 2+ named routes. See Several routes.
imagebooleanfalseAlso 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.
titlestringgeneratedMap title for the page, the link preview and the alt text.
descriptionstringgeneratedOne-line summary shown under the title and in link previews.
basemapstringautoauto (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.
lockbooleantrue on blank, else falseKeep 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_bystring—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_labelsobject—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}.
palettestringbluesblues, 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).
classesinteger5Number of color classes for color_by, 3 to 7.
markerstringby point countpin, 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.
colorstring#2563ebColor for every feature that has no color of its own: hex (#e11d48, e11d48, #e14) or a basic name like red.
clusterbooleanby point countGroup nearby points into numbered bubbles that split as you zoom in.
directionsbooleantrueA "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.
labelsbooleanfalseDraw each feature's title as a text label on the map.
center[lng, lat]fit to dataInitial map center. Longitude first, as in GeoJSON.
zoomnumberfit to dataInitial 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 pin markers that can hold an emoji or a number. Above 300, points render as dot, a GPU circle layer that stays responsive with tens of thousands of points.
  • Clustering. Turns on above 1,000 points. Send "cluster": false to draw every point.
  • Title. One to three named features give "A, B & C". A connect route 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 in alt_text, markdown and the page's og: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:

TypeDraws as
Point, MultiPointPins or dots
LineString, MultiLineStringLines. The popup shows the length.
Polygon, MultiPolygonFilled areas with an outline. Holes are supported.
GeometryCollectionEach member by its type
Feature, FeatureCollectionTheir 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.

PropertyApplies toExampleEffect
titleall"Café Louvre"Popup heading, and the label when labels is on
descriptionall"Open 8–22"Popup text; https URLs in it become links
marker-colorpoints"#e11d48"Pin or dot color
url, websiteall"https://example.com/menu""Website" button in the popup ("Open link" on lines and areas; https only)
addressall"Mariahilfer Str. 10, Vienna"Popup details, first in the list
phoneall"+43 1 234 5678"Tap-to-call link
opening_hoursall"Mo-Fr 8-18, Sa 9-16"Shown as "Opening hours"
price, ratingall"€€", 4.6Popup details
email, instagramall"hi@example.com", "@handle"mailto link; link to the Instagram profile
imageall"https://example.com/photo.jpg"Photo at the top of the popup (https only; hidden if it fails to load)
marker-sizepoints"small", "medium", "large"Pin size
marker-symbolpoints"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.
strokelines, outlines"#0f766e"Line color
stroke-widthlines, outlines3Line width in pixels
stroke-opacitylines, outlines0.80 to 1
fillpolygons"#14b8a6"Area color
fill-opacitypolygons0.30 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" }
Iconmarker-symbolAlso accepted
restaurantfood, dining, eat
cafecoffee, café
barpub, beer, drinks, nightlife
shopshopping, store, market
lodginghotel, accommodation, hostel, bed
museumattraction, sight, sightseeing, landmark, culture
parknature, garden, tree
railtrain, station, transit, metro
airportplane, flight
hospitalhealth, 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 with 400 only when nothing is left to draw.
  • Mixing. places and data can 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, foot or transit. Aliases driving, cycling, walking and, for transit, public_transport, metro, subway, bus, tram, train work too, and true means car. An unknown mode is a 400 that lists them. transit is 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, foot or transit, default foot), places (same forms as top-level places), color (optional; an auto palette is used otherwise), remove (true deletes the route). Stops are numbered 1, 2, 3 per route. Each route falls back to straight lines on its own, with a reason in the response.
  • 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). 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 transit leg 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 places plus 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 is tabs with 2+ named routes. On the map URL, ?route=2, ?route=Day%202 or ?route=all opens a route, and ?route_view=together overrides the mode.
  • Shared features. Top-level places, data and areas can be combined with routes. They are shown with every route.
  • Add routes to an existing map. PUT the GET body with routes appended, or call the MCP tool update_map with changes: {"routes": [ …new routes only… ]}. Existing routes and features are kept. A route given with places replaces the route of the same name. {"name": "Day 1", "remove": true} deletes one. Without places, {"name": "Day 1", "color": "#e11d48"} recolors it and a different mode re-routes it from its stops. To switch a whole route to driving, send {"name": "Day 1", "mode": "car"} (PUT or update_map) with no places: every leg gets that mode (also from transit), per-place modes are replaced, nothing is re-geocoded and the link stays the same. An unknown name without places is a 400.
  • Single route. route and connect still work as before for one route through places.

Response

A successful create returns 201 with these fields:

FieldTypeDescription
idstring10-character map ID, for example k3f9q2xa7b.
urlstringThe map page. This is the link to give the user.
image_urlstring?1200×630 PNG preview. Only present with "image": true. See PNG preview.
data_urlstringThe normalized GeoJSON FeatureCollection. See Raw GeoJSON.
titlestringYour title, or the generated one.
descriptionstringYour description, or the generated one.
alt_textstringAlt text for the preview image.
preview_urlstringThe 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_markdownstring[![alt_text](preview_url)](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.
markdownstringA link to the map, [title](url). With "image": true it's the preview image linked to the map, [![alt_text](image_url)](url), which renders in GitHub, Slack, Discord and most chat UIs.
routeobject?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.
routesarray?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_htmlstringAn <iframe> of the map with ?embed=1.
edit_tokenstringSecret for PUT /v1/maps/{id} (Authorization: Bearer). Only in the create response, never shown again: only a hash is stored. Keep it private.
edit_urlstringLink 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.
expiresstringThe lifetime rule in words: "Deleted after 30 days without views".
feature_countnumberFeatures on the map, including geocoded places and the connect line.
bbox[w, s, e, n]Bounding box of all features: west, south, east, north.
warningsstring[]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.

ParameterValuesExample
basemapa basemap name or alias?basemap=dark
markerpin, circle, dot, none?marker=circle
colorhex color, # encoded as %23?color=%23e11d48
cluster1 or 0?cluster=1
labels1 or 0?labels=1
embed1?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=1

The PNG preview always uses the settings stored at creation.

Basemaps

All basemaps are OpenFreeMap vector styles.

NameLookAliases
autoThe 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.—
positronLight grey and quiet, so your data stands out. Always light.light, default
libertyFull-color street map with buildings and land use.streets
brightStreet map with saturated road and water colors.—
darkDark grey. Use light marker colors.—
fiordDark blue-grey.—
blankNo map tiles: only your data on a plain light background. For editorial, choropleth and blind maps. lock defaults to on.none
blank-darkThe same on a dark background.—
blank-autoLight 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 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" finds "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 without any data.
  • Defaults: blank basemap with lock, labels on (up to 60 areas), title "<Area> by <color_by>" or the area name. areas can be combined with data and places; pins and lines are drawn on top.
  • GET /v1/maps/{id} returns the resolved polygons in data (no areas field), so a PUT does not refetch. Errors: 400 "No area named …" or unknown level, 502 when 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]]]}}
 ]}}

Images, embeds & sharing

Every map has a page, a PNG, an embed, an oEmbed entry and its GeoJSON. Loading the page, the PNG or the GeoJSON counts as a view and keeps the map alive.

PNG preview

Every map has a 1200×630 PNG preview, the size Open Graph link previews expect, at GET https://maps.polygrid.dev/m/:id.png, and its page carries it as og:image. A headless browser screenshots the map the first time the PNG is requested (5–10 s; a request that arrives mid-render waits for it) and stores it until the map is edited. With "image": true the render starts at create and the response includes image_url. Renders are limited: past the daily quota the PNG returns 503 and link previews show without an image.

Rendering has a daily budget. When it's used up, the PNG URL serves a generic "Open the map" placeholder card (status 200, cached for 60 s, Retry-After header, so chat images never break); clients that send Accept: application/json get 503 instead. The map page keeps working.

Iframe embed

embed_html in the response is ready to paste. It loads the map with ?embed=1, which hides the title panel:

<iframe
  src="https://maps.polygrid.dev/m/k3f9q2xa7b?embed=1"
  width="100%" height="450" style="border:0"
  loading="lazy" title="Coffee in Prague"></iframe>

oEmbed

WordPress, Discourse, Ghost and other oEmbed-aware tools turn a pasted map URL into an embedded map. Map pages advertise the endpoint with <link rel="alternate" type="application/json+oembed">, or call it directly:

curl "https://maps.polygrid.dev/oembed?url=https://maps.polygrid.dev/m/k3f9q2xa7b"
{
  "version": "1.0",
  "type": "rich",
  "title": "Coffee in Prague",
  "html": "<iframe src=\"https://maps.polygrid.dev/m/k3f9q2xa7b?embed=1\" …></iframe>",
  "width": 1200,
  "height": 630,
  "thumbnail_url": "https://maps.polygrid.dev/m/k3f9q2xa7b.png"
}

Link previews

Map pages carry og:title, og:description, og:image (the PNG, with width, height and alt text, when the map has one) and twitter:card=summary_large_image (otherwise summary). Paste a map URL into Slack, Discord, iMessage or X and it unfurls with the title and the preview image. Map pages are marked noindex, so they don't show up in search engines.

Raw GeoJSON

GET https://maps.polygrid.dev/m/:id.geojson returns the map's data as a FeatureCollection with Content-Type: application/geo+json. It's normalized: coordinates are [lng, lat], every feature has a properties object, geocoded places are Point features, and generated colors and pin numbers are written into the simplestyle properties. Map pages link to it with <link rel="alternate" type="application/geo+json">.

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 as POST /v1/maps and returns the same fields as the response.
claude mcp add --transport http polygrid-maps 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:

How to answer the user

  • Put the share link (url) first, on its own line, then one line about what the map shows, then any warnings in plain words.
  • Start with preview_markdown only 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_url as "your private edit link (lets you change the map later; don't share it)". Never show the raw edit_token in chat; keep it for your own PUT / update_map calls.
  • 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 places instead 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 with preview_markdown (the map thumbnail); otherwise post the markdown field. Ask for "image": true only when you'll show the preview image.
  • Check route.status. If it's straight, 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 title when 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=dark to url instead 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 the edit_token, GET the body, change it and PUT it 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.

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.

StatusMeaningWhat to do
400Invalid 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 / 403On PUT: the edit token is missing (401) or wrong (403).Send Authorization: Bearer <edit_token> from the create response.
404The map doesn't exist or has expired.Create it again.
413Request body is larger than 2 MB.Simplify geometry or drop unused properties.
429More than 60 maps created in a minute from your IP.Wait for the Retry-After seconds.
503PNG 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

LimitValue
Map lifetimeDeleted 30 days after the last view of the page, PNG or GeoJSON, or the last update. Maps can't be deleted sooner.
Request body2 MB
Places per request50
Rate limit60 map creations or updates per minute per IP, REST and MCP combined
PNG rendersDaily 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.