Skip to main content

Agent recipes

Six common jobs. Each one is what you type, and what the server does with it.

A table of numbers into a choropleth​

Map this. Dark theme, and put the unit in the legend.

FI 12, NO 9.9, IS 9, DK 8.7, BR 5.8, DE 5.5, US 4.2, JP 3.6

One create_map call. The numbers go in as structured values, not as a packed string.

{
  "scope": "world",
  "theme": "dark",
  "width": 900,
  "title": "Coffee consumption per capita",
  "subtitle": "kg per person per year",
  "legendTitle": "kg / person",
  "values": [
    { "id": "FI", "value": 12 },
    { "id": "NO", "value": 9.9 },
    { "id": "IS", "value": 9 },
    { "id": "DK", "value": 8.7 },
    { "id": "BR", "value": 5.8 },
    { "id": "DE", "value": 5.5 },
    { "id": "US", "value": 4.2 },
    { "id": "JP", "value": 3.6 }
  ]
}
World choropleth of coffee consumption per capita

If your table has country names rather than ISO codes, the assistant should resolve them with find_places first — "Ivory Coast" and "Côte d'Ivoire" are both CI, and guessing is how a row goes missing.

Highlight a set of countries​

Show the EU members that joined from 2004 onwards. No legend.

No values, so highlight rather than values. The EU scope crops the map to the union instead of showing the whole world.

{
  "scope": "EU",
  "theme": "dark",
  "width": 900,
  "title": "EU members that joined from 2004",
  "legend": false,
  "highlight": ["CY", "CZ", "EE", "HU", "LV", "LT", "MT", "PL", "SK", "SI", "BG", "RO", "HR"]
}
EU scope with the member states that joined from 2004 highlighted

Place names into a marker map​

Put our three transshipment ports on a world map: Shanghai, Singapore, Rotterdam.

Two steps, and the first one matters. find_places resolves each name to coordinates; only then is there anything to draw.

{ "query": "Shanghai", "kind": "city" }

That returns 31.23, 121.47, and the same again for the other two ports. Then a create_map for the base map, and add_layers for the resolved points:

{
  "map": "https://api.maproll.io/map.svg?scope=world&theme=dark&width=900",
  "markers": [
    { "lat": 31.23, "lon": 121.47, "icon": "anchor", "label": "Shanghai" },
    { "lat": 1.29, "lon": 103.85, "icon": "anchor", "label": "Singapore", "labelPosition": "bottom" },
    { "lat": 51.92, "lon": 4.48, "icon": "anchor", "label": "Rotterdam" }
  ]
}
Three ports marked with anchors on a dark world map

Skipping find_places is the single most common way to get a confidently wrong map: a marker a few degrees off looks exactly as deliberate as a correct one.

Add a shipping route to a map you already have​

Now draw the sea route from Shanghai to Rotterdam.

add_layers on the previous URL, with sea: true. A great circle between those two ports crosses Siberia; sea threads the maritime network through Suez instead.

{
  "map": "<the svg_url from the previous call>",
  "routes": [
    {
      "from": "31.23,121.47",
      "to": "51.92,4.48",
      "sea": true,
      "color": "#0066cc",
      "width": 3,
      "arrow": true
    }
  ]
}
Sea route from Shanghai to Rotterdam via Suez

The markers are untouched. add_layers appends — the route is added to what the URL already carried.

A map for a README​

Make a light-theme map of the countries we ship to, and give me the markdown to paste into the README.

The readme_map prompt does this in one step: a light theme, because most READMEs render on a light ground, and alt text that says what the map shows rather than "map".

Ask for it by hand and you get a create_map call plus the embed field from the response, which is already an <img> tag. For markdown:

![Countries we ship to](https://api.maproll.io/map.svg?scope=world&theme=light&width=900&regions=US,DE,IN,BR,JP&title=Where%20our%20users%20are)
Light world map highlighting the United States, Germany, India, Brazil and Japan

Two things to know before you commit it. The URL is permanent and cached, so a README image costs nothing to serve. And an unkeyed MCP render carries the maproll wordmark — if that is not what you want on your project page, set a key first (Install).

Hand it to a person​

Good enough. Open it in the editor.

No tool call. Every map response already includes editor_url; opening it loads that exact map in app.maproll.io, editable.

That is the handoff for the things a conversation is bad at — nudging a label off a border, trying four themes, picking a break by eye. Whatever comes back out of the editor is still just a URL, so it can go straight into add_layers if the assistant has more to add.

  • Tools — every argument these calls draw on.
  • Working with existing maps — why the URL is the only handle you need.
  • Prompts — mapped_episode, readme_map and refine_map, for the jobs that come up often.