Tools

Four tools, modelled on jobs rather than on the ~30 query parameters of the render API. The full parameter surface is still reachable — see extra — but a model does not have to wade through it to make a map.

create_map

Makes a map. The only required argument is scope.

Region data arrives structured, not as the packed data= string:

{
  "scope": "world",
  "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": "US", "value": 4.2 }
  ]
}

Each entry in values takes one of four forms, matching the data grammar:

Form	Produces
{ id, value }	A choropleth, binned by classification and coloured by colorScale.
{ id, value, color }	The same, with an explicit fill overriding the scale for that region.
{ id, color }	Flat paint with no value behind it. Pair with legend: false.
{ id, category }	A qualitative bucket. Selects a categorical scale and names the bucket in the legend.

Numeric values and text categories cannot appear in the same map. The server rejects the combination and names the offending ids, rather than letting the renderer return a 400 the assistant has to reverse-engineer.

For a map about which regions rather than how much, use highlight instead of values:

{ "scope": "EU", "highlight": ["RO", "DE", "FR"], "legend": false }

extra

Anything documented in these pages but without a dedicated field — patterns, annotations, proportional, labelMinArea — passes through extra verbatim:

{ "scope": "world", "extra": { "labelMinArea": 400, "patterns": "DE:dots" } }

add_layers

Takes a map URL and adds to it. Everything already on the map is kept, so this is how a map is built up over several turns rather than rebuilt from scratch each time.

{
  "map": "https://api.maproll.io/map.svg?scope=world&theme=dark",
  "markers": [
    { "lat": 44.17, "lon": 28.65, "icon": "anchor", "label": "Constanța" }
  ],
  "routes": [
    { "from": "31.23,121.47", "to": "51.92,4.48", "sea": true, "arrow": true }
  ]
}

Accepts markers, routes, proportional, patterns, annotations and labels. Pair-list parameters append rather than replace.

sea: true follows the maritime network through Suez, Panama and Malacca instead of drawing a great circle over land — see routes.

find_places

Resolves a place name to real coordinates and the id maproll uses.

{ "query": "Constanța", "kind": "city" }

Returns each hit's name, kind, id (ISO 3166-1 alpha-2 for countries, ISO 3166-2 for regions, IATA for airports), latitude, longitude, and its parent country and region.

Use it before placing any marker or lat,lon route endpoint. This is the one thing an assistant genuinely cannot do from memory: recalled coordinates are routinely wrong by degrees, and the renderer will happily draw the marker wherever it is told.

Searches countries, regions, cities and airports. Omit kind to search all four.

describe_options

Returns the exact accepted values for scopes, themes, icons, projections, patterns, or the URL grammar.

{ "kind": "icons" }

The same content is published as resources; this tool exists for clients that do not read resources. An invented theme or icon name renders nothing and reports no error, so checking beats guessing.