Ultimaps

Working · 1.8 s

com.ultimaps/mcpv0.2.0 Domain verified

Create choropleth, category and pin maps of countries, states, counties and ZIP codes as images.

Maps & Travel

Source Website Registry entry

Try it

Call this server's tools from your browser. Nothing to install.

https://api.ultimaps.com/mcp

Authorization (optional)

Optional. Bearer <your Ultimaps API key> for plan quotas. Without a key you get 30 maps per hour per conversation, with attribution.

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

get_map_regions

Look up one map: title, regionType, regionCount, labels, layers, and its regions as {key, title}, 200 per page. You rarely need this before rendering. render_map accepts region names, codes and common aliases and auto-corrects typos, reporting what it matched. Use it to build a dataset covering every region of a map, to see how a map names its regions, or to resolve a key render_map could not match. `query` searches keys, titles and aliases, so no hits means the map really has no such region. Use `offset` for further pages.

mapIdstring, required

Map id from list_maps, e.g. "united-states", "europe", "united-states-california".

querystring

Search region keys, titles and aliases, e.g. "saint" or "US-TX". Omit to page through every region.

offsetinteger

Skip this many regions. Pages hold 200 regions; use the offset the previous result names.

Tools (3)

get_map_regions

read-only

Argument	Type	Description
mapId*	string	Map id from list_maps, e.g. "united-states", "europe", "united-states-california".
query	string	Search region keys, titles and aliases, e.g. "saint" or "US-TX". Omit to page through every region.
offset	integer	Skip this many regions. Pages hold 200 regions; use the offset the previous result names.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "mapId"
  ],
  "properties": {
    "mapId": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "Map id from list_maps, e.g. \"united-states\", \"europe\", \"united-states-california\"."
    },
    "query": {
      "type": "string",
      "maxLength": 100,
      "description": "Search region keys, titles and aliases, e.g. \"saint\" or \"US-TX\". Omit to page through every region."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Skip this many regions. Pages hold 200 regions; use the offset the previous result names."
    }
  },
  "additionalProperties": false
}

list_maps

List the maps Ultimaps can render: the world, continents, countries subdivided into states, provinces, counties or departments, and US ZIP code areas. Each row is {id, title, regionType, layers, regionCount, labels}. `id` is the mapId for render_map and get_map_regions; it is the map's slug on ultimaps.com (the last path segment, not the whole URL) and always means the current edition. `regionCount` is how many region keys a complete dataset needs. `labels: false` means the map has no region labels, so `style.labels` does nothing there. `layers` are the ids render_map's `layers` can turn on. Pass `query` to search ids, titles, region types and categories (e.g. "counties", "germany", "africa"). Only call this when you don't know the id: common ids such as `world`, `united-states` and `europe` just work, and an unknown id usually comes back with the closest ids.

read-only

Argument	Type	Description
query	string	Search map ids, titles, region types and categories, e.g. "counties", "germany", "africa". Omit to list every map.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 100,
      "description": "Search map ids, titles, region types and categories, e.g. \"counties\", \"germany\", \"africa\". Omit to list every map."
    }
  },
  "additionalProperties": false
}

render_map

Draws a map of real places as an image: countries, states, counties or ZIP codes colored by data (a choropleth or heat map) or by category, with a legend, a title and pins. Borders come from real geographic data, not from an image model, and region names are matched for you. It draws only real places, never fictional or invented ones. The map is returned as an image in the conversation. Maps cover the world, continents, countries, their states, provinces and counties, and US ZIP code areas. Color regions with ONE of these (choropleth and categories are mutually exclusive): - `choropleth`: a number per region, e.g. {"values": {"California": 39.5, "Texas": 30.5}}. Classes, breaks and palette are picked from the data unless you set them. Say what the numbers are with `kind` (and `midpoint` when they have a meaningful center, `unit` for a short label unit): that is what gets percents, currencies, years and diverging scales right. When the data does not cover every region of the map, add `noData: true` so the legend explains the uncolored ones. - `categories`: a label per region, e.g. {"values": {"France": "Euro", "Poland": "Złoty"}}. Colors are assigned automatically unless you set `colors`. - `regions`: explicit hex colors, e.g. {"Texas": "#1D4ED8"}. Also works on top of either mode as an override. Region keys can be names, ISO/FIPS-style codes or common aliases. Typos are auto-corrected, and every correction or unmatched key is reported with suggestions, so there is no need to call get_map_regions first. Get `mapId` from list_maps if you don't know it. Also available: pins (`locations` with lat/lon), `title`, `legend` (position, `title`, `subtitle`), `style` (theme, borders, region labels; `style.labels.content: "value"` prints each region's value instead of its name and `"name_value"` stacks the name above the value, both needing `choropleth` or `categories`; `style.labels.fit` (default "auto") shortens labels that don't fit or overlap and never hides one; any still overlapping are reported in a `labels_overlap` warning with their keys), extra `layers`, and `output` size. A data legend needs a `legend.title`: what is measured, its unit and the year ("Median household income (US$, 2023)"). An untitled legend leaves the reader guessing. Short units ("%", "°C", "t") go in `choropleth.unit`, long ones ("litres per person") in the legend title. `dryRun: true` validates and previews region matching and the color plan without rendering. Without an API key: 30 renders per hour and 5 per minute per conversation (dry runs count), PNG up to 1600 px wide, with Ultimaps attribution on the image. The default 1200 px width is right for viewing in chat, and larger images are returned only as a link. Formats: png. SVG and PDF export are in Ultimaps Studio, from the edit link in the result. Every result includes an image link that works for 30 days, for chat apps that do not display images returned by tools. The result reports corrections, warnings, the resolved color plan, and an edit link that opens the map in Ultimaps Studio, where it can be edited, exported, or published as an interactive, clickable map to embed on a website (free account).

Argument

Type

Description

mapId*

string

Map id from list_maps, e.g. `world`, `united-states`, `europe`, `united-states-california`. It is the map's slug on ultimaps.com (the last path segment, not the whole URL) and always resolves to the current edition.

style

object

title

object

dryRun

boolean

Validate and preview without rendering: returns the region matching report, the resolved choropleth plan and a legend preview. No image and no monthly quota for keyed calls, but it still counts against the rate limit (one of the anonymous renders per hour without a key).

layers

object

Extra geographic layers to draw, e.g. {"cities": true, "roads": true}. Each map ships a subset (`layers` in list_maps and get_map_regions). Turning on a layer the map lacks is not an error: it is skipped with a `layer_unavailable` warning. Omitted layers are off, except layers a map turns on by default (currently `admin0` on ZIP-code maps); pass false to hide those.

legend

object

output

object

Image size and format. Keep the default width (1200 px) for images viewed in the conversation: much larger renders, and any scale of 2 or more, are too big to show inline and are returned as a link instead. Without an API key: width up to 1600 px, an explicit height up to 1600 px, scale 1. Hard caps: width×scale and height×scale ≤ 8192, and at most 4096×4096 pixels in total.

regions

object

Override layer. Region key to hex color, applied AFTER choropleth/categories coloring and winning over it. Precedence: choropleth/categories paint first, `regions` overrides win, and everything else gets `choropleth.noDataColor` (choropleth mode), else `style.defaultRegionColor`, else the theme default (in choropleth mode, a contrasting gray when the theme's region color is too close to the palette's lightest class).

locations

array

Pin markers. They compose with every mode.

categories

object

Categorical coloring mode. Mutually exclusive with `choropleth`. Unmatched keys simply leave their regions uncolored. The no-data fill is `style.defaultRegionColor`, and `noDataColor` does not apply here.

choropleth

object

Numeric choropleth mode. Mutually exclusive with `categories` (one scale per map). `regions` composes with it as an override layer. If none of the keys in `values` match, the request fails even under `onUnmatched: warn`, since there is nothing to build a scale from. `type`, `classes`, `method` and `palette` are all optional: whatever you leave out is suggested from the data, and the resolved plan is reported in the result. Do send `kind` whenever you know what the numbers are, `midpoint` when they have a meaningful center, and a short `unit`: the values alone cannot tell 42% from 0.42 or a change from a level.

onUnmatched

string

warn = render anyway (unmatched regions get the no-data fill) and report. error = 400 with per-key suggestions. Recommended for production pipelines: error. Exception: in choropleth mode, ZERO matched keys is a 400 even under warn. Region keys in `style.labels.hide` count too: a typo there is a 400 under error.

{ "type": "object", "required": [ "mapId" ], "properties": { "mapId": { "type": "string", "examples": [ "united-states" ], "maxLength": 120, "minLength": 1, "description": "Map id from list_maps, e.g. `world`, `united-states`, `europe`, `united-states-california`. It is the map's slug on ultimaps.com (the last path segment, not the whole URL) and always resolves to the current edition." }, "style": { "type": "object", "properties": { "theme": { "enum": [ "paper", "newspaper", "dark", "earth", "vintage", "embossed", "maritime", "neon", "outline", "wireframe" ], "type": "string", "default": "paper", "description": "Theme name from Studio's theme gallery (the server matches case-insensitively). Additive-only enum.\n" }, "labels": { "type": "object", "properties": { "fit": { "enum": [ "auto", "off" ], "type": "string", "default": "auto", "description": "`auto` shortens labels that don't fit or overlap and never hides one; `off` draws every label in full. Under `auto` a `name_value` label too big for its region, or overlapping a higher-priority one, drops to its value (choropleth; the legend only gives a range) or its name (categories; the fill already says the category). Priority: curated outside labels (small regions labeled beside the map), then larger regions. Labels still overlapping are drawn and reported in a `labels_overlap` warning. Studio's own default is off; a map opened in Studio from a render keeps the value sent." }, "hide": { "type": "array", "items": { "type": "string", "maxLength": 200, "minLength": 1 }, "maxItems": 5000, "description": "Region keys whose label never shows. Matched like data keys; corrections and misses are reported in `regionMatching`. Ignored with a `label_lists_ignored` warning when `show` is false." }, "show": { "type": "boolean", "default": false }, "color": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ] }, "content": { "enum": [ "name", "value", "name_value" ], "type": "string", "default": "name", "description": "What each label prints. `name` is the region's name. `value` prints the region's value instead: the choropleth number formatted by the resolved `choropleth.format` (the same string the legend and tooltips show), or the category label. Regions without a value get no label. `name_value` prints the name with the value on a line below it; regions without a value show the name only. Both value modes require `choropleth` or `categories`; with neither it is a `validation_error`." } }, "description": "Region labels, off by default. Each map ships its own curated label set; on a map with `labels: false` in list_maps, `show: true` renders nothing and a `labels_unavailable` warning is reported. `content`: \"name\" (default), \"value\" (the choropleth number in the legend's format, or the category label; regions without data get no label) or \"name_value\" (name above value; regions without data show the name only). `fit`: \"auto\" (default) shortens labels that don't fit or overlap (to the value on a choropleth, the name on a category map); labels never disappear, and any still overlapping are listed in a `labels_overlap` warning. \"off\" draws every label in full. `hide`: region keys whose label never shows (matched like data keys). A typo is auto-corrected or reported as unmatched; under `onUnmatched: \"error\"` an unmatched key fails the request like a data key.", "additionalProperties": false }, "mapBorder": { "type": "object", "properties": { "color": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ] }, "width": { "type": "number", "maximum": 10, "minimum": 0 } }, "additionalProperties": false }, "regionBorders": { "type": "object", "properties": { "color": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ] }, "width": { "type": "number", "maximum": 5, "minimum": 0 } }, "additionalProperties": false }, "backgroundColor": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ] }, "defaultRegionColor": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ], "description": "Fill for regions that get no color from `choropleth`/`categories`/`regions`. In choropleth mode `choropleth.noDataColor` overrides this. In categories mode this IS the no-data fill.\n" } }, "additionalProperties": false }, "title": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 200, "minLength": 1 }, "color": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ] }, "position": { "enum": [ "top", "bottom" ], "type": "string", "default": "top" } }, "additionalProperties": false }, "dryRun": { "type": "boolean", "default": false, "description": "Validate and preview without rendering: returns the region matching report, the resolved choropleth plan and a legend preview. No image and no monthly quota for keyed calls, but it still counts against the rate limit (one of the anonymous renders per hour without a key)." }, "layers": { "type": "object", "properties": { "lakes": { "type": "boolean", "description": "Major lakes." }, "roads": { "type": "boolean", "description": "Major roads." }, "admin0": { "type": "boolean", "description": "Surrounding land, as a filled area of neighboring countries or states." }, "cities": { "type": "boolean", "description": "Major cities as labeled points." }, "rivers": { "type": "boolean", "description": "Major rivers." }, "admin0-mesh": { "type": "boolean", "description": "Country borders (mesh)." }, "admin1-mesh": { "type": "boolean", "description": "First-level subdivision borders (states, provinces, regions)." }, "admin2-mesh": { "type": "boolean", "description": "Second-level subdivision borders (counties, districts)." }, "admin1-mesh-inner": { "type": "boolean", "description": "State borders drawn over the map's own regions (county and ZIP maps, where `admin1-mesh` covers the surroundings only)." } }, "description": "Extra geographic layers to draw, e.g. {\"cities\": true, \"roads\": true}. Each map ships a subset (`layers` in list_maps and get_map_regions). Turning on a layer the map lacks is not an error: it is skipped with a `layer_unavailable` warning. Omitted layers are off, except layers a map turns on by default (currently `admin0` on ZIP-code maps); pass false to hide those.", "additionalProperties": false }, "legend": { "type": "object", "properties": { "show": { "type": "boolean", "description": "Defaults to true whenever a legend exists (auto-generated for `choropleth`/`categories`, or from `legend.items`). Set false to suppress it and give the whole canvas to the map.\n" }, "items": { "type": "array", "items": { "type": "object", "required": [ "label", "color" ], "properties": { "color": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ] }, "label": { "type": "string", "maxLength": 120, "minLength": 1 } }, "additionalProperties": false }, "maxItems": 50, "minItems": 1, "description": "Manual legend items, for regions-only maps. With `choropleth` or `categories` the legend is auto-generated and `items` is rejected with 400.\n" }, "title": { "type": "string", "maxLength": 120, "minLength": 1, "description": "Heading above the legend rows. Send one for every data legend: what is measured, its unit and the year, e.g. \"Median household income (US$, 2023)\". It is never derived from `choropleth.unit`: short units (\"%\", \"°C\") go in `unit` and print on every label, long ones belong here. Long titles wrap to fit the legend; `\\n` forces a break." }, "position": { "enum": [ "left", "right", "top", "bottom" ], "type": "string", "description": "left/right take a column carved from the map area (180 px, widened up to 260 px for long labels or a legend title, at most 30% of the width); top/bottom take a horizontal band between the title and the map. Absent = picked per render: inside the map over empty space (sea, the margin beside a narrow map) when the legend fits there clear of land, else gradient/steps go to the bottom band and item/group legends to the left column or the bottom band, whichever leaves the map larger. Leave it out unless you need the legend outside the map. Gradient and steps legends are horizontal-only, so left/right becomes bottom with a warning. Band items wrap into rows; a bar too wide for a narrow image is reported as a `legend_overflow` warning." }, "subtitle": { "type": "string", "maxLength": 160, "minLength": 1, "description": "Line under the legend title, at the label size in the regular weight, e.g. the source or the base year. Same wrapping as `title`.\n" } }, "additionalProperties": false }, "output": { "type": "object", "properties": { "scale": { "type": "number", "default": 1, "maximum": 4, "minimum": 1, "description": "PNG raster multiplier: the PNG is exactly round(width×scale) × round(height×scale) pixels. It has no effect on SVG output, but it is still tier-capped.\n" }, "width": { "type": "integer", "default": 1200, "maximum": 4000, "minimum": 100, "description": "Image width in pixels. Default 1200." }, "format": { "enum": [ "png", "svg" ], "type": "string", "default": "png", "description": "`png` (default) or `svg`. `svg` works only with an API key that allows it, and is returned as a link; otherwise export SVG in Ultimaps Studio. PDF is not available." }, "height": { "type": "integer", "maximum": 4000, "minimum": 100, "description": "Optional. When omitted, derives as a snug fit: the map's aspect ratio applied to the map area that remains after the title band (50 px) and any left/right legend column take their cut. A top/bottom legend adds its band (60 px for item legends, 70 px for gradient/steps bars, plus the height of a `legend.title`/`subtitle`) on top of that. A left/right legend too tall for that canvas (many items, a wrapped title) grows the derived height until it fits. An explicit height is delivered exactly, and the title and legend then shrink the map rather than the canvas.\n" } }, "description": "Image size and format. Keep the default width (1200 px) for images viewed in the conversation: much larger renders, and any scale of 2 or more, are too big to show inline and are returned as a link instead. Without an API key: width up to 1600 px, an explicit height up to 1600 px, scale 1. Hard caps: width×scale and height×scale ≤ 8192, and at most 4096×4096 pixels in total.", "additionalProperties": false }, "regions": { "type": "object", "description": "Override layer. Region key to hex color, applied AFTER choropleth/categories coloring and winning over it. Precedence: choropleth/categories paint first, `regions` overrides win, and everything else gets `choropleth.noDataColor` (choropleth mode), else `style.defaultRegionColor`, else the theme default (in choropleth mode, a contrasting gray when the theme's region color is too close to the palette's lightest class).\n", "maxProperties": 5000, "additionalProperties": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ] } }, "locations": { "type": "array", "items": { "type": "object", "required": [ "title", "lat", "lon" ], "properties": { "lat": { "type": "number", "maximum": 90, "minimum": -90 }, "lon": { "type": "number", "maximum": 180, "minimum": -180 }, "color": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ] }, "title": { "type": "string", "maxLength": 120, "minLength": 1 }, "showLabel": { "type": "boolean", "default": true, "description": "Set false to render this pin without its label (the marker stays).\n" }, "labelPosition": { "enum": [ "top", "bottom", "left", "right" ], "type": "string", "default": "bottom", "description": "Where the pin's label sits relative to the pin." } }, "additionalProperties": false }, "maxItems": 200, "description": "Pin markers. They compose with every mode." }, "categories": { "type": "object", "required": [ "values" ], "properties": { "colors": { "type": "object", "description": "Optional category name to color. Names are matched exactly and case-sensitively against the names in `values` (unlike region keys, which are matched loosely). An entry for a category no region uses is silently ignored. Unlisted categories get a color from a built-in categorical palette, assigned in order of first appearance in `values`, so pin the colors if you need stable output.\n", "additionalProperties": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ] } }, "values": { "type": "object", "description": "Region key to category name.", "maxProperties": 5000, "minProperties": 1, "additionalProperties": { "type": "string", "minLength": 1 } } }, "description": "Categorical coloring mode. Mutually exclusive with `choropleth`. Unmatched keys simply leave their regions uncolored. The no-data fill is `style.defaultRegionColor`, and `noDataColor` does not apply here.\n", "additionalProperties": false }, "choropleth": { "type": "object", "required": [ "values" ], "properties": { "kind": { "enum": [ "count", "rate", "percent", "fraction", "currency", "change", "year", "index" ], "type": "string", "description": "What the numbers are. Send it whenever you know. `percent` = already ×100 (42 prints \"42%\"), `fraction` = a 0–1 share (0.42 prints \"42%\"), `currency` (set `unit` to the code, e.g. \"EUR\"), `year` (1788, no separator), `change` (signed labels, diverging around 0), or `count`, `rate`, `index`. Once a kind is given, the palette is diverging only with `midpoint` or `kind: \"change\"`, so data that merely dips below zero stays sequential." }, "type": { "enum": [ "auto", "gradient", "steps", "groups" ], "type": "string", "default": "auto", "description": "Visualization type. `auto` picks from the data: ≤7 unique values → `groups` (discrete legend items), skewed distributions → `steps` (contiguous bar with break ticks), else `gradient` (continuous color scale). Explicit values pin the type. `gradient` and `steps` legends are horizontal-only: they render in a top/bottom band (default bottom), and a left/right `legend.position` is coerced to bottom with a warning. That rule depends on the data, so JSON Schema cannot express it and generated SDKs should not try to enforce it.\n" }, "unit": { "type": "string", "maxLength": 16, "minLength": 1, "description": "Short unit printed on every label, up to 16 characters: \"%\", \"°C\", \"t\", \"km²\". Put long units (\"litres of pure alcohol per person\") in `legend.title` instead. With `kind: \"currency\"` it is the currency code or symbol. Ignored for `kind: \"fraction\"` and when `format` is set, except {\"locale\": \"de-DE\"} (or {\"preset\": \"auto\", \"locale\": \"de-DE\"}), which keeps kind and unit in that number style. An explicit `format` decides only the labels: `kind` and `midpoint` still decide sequential vs diverging." }, "format": { "type": "object", "properties": { "d3": { "type": "string", "maxLength": 20, "description": "Escape hatch: a raw d3-format spec. Invalid grammar is a 400.\n" }, "sign": { "enum": [ "auto", "always", "exceptZero" ], "type": "string", "default": "auto", "description": "Maps 1:1 to Intl signDisplay. \"exceptZero\" is the usual choice for diverging legends.\n" }, "trim": { "type": "boolean", "description": "Strip trailing zeros." }, "style": { "enum": [ "decimal", "percent", "currency" ], "type": "string", "default": "decimal", "description": "\"percent\" MULTIPLIES BY 100. The input is a fraction (0.42 prints as \"42%\"). Data already in percent points should use `suffix: \"%\"` instead.\n" }, "locale": { "enum": [ "en-US", "de-DE", "fr-FR", "es-ES", "it-IT", "pt-BR", "de-CH", "en-IN", "nl-NL", "pl-PL", "sv-SE" ], "type": "string", "default": "en-US", "description": "Number style: separators, currency placement and compact suffixes. `{\"decimals\": 1, \"locale\": \"de-DE\"}` turns 1234567.5 into \"1.234.567,5\"; with `compact: true` it gives \"1,2 Mio.\". Combines with `preset` and `d3`; on its own (`{\"locale\": \"de-DE\"}`) it is the automatic format in that number style.\n" }, "prefix": { "type": "string", "maxLength": 12, "description": "Literal, inserted AFTER any leading sign (\"-€1,234\", never \"€-1,234\").\n" }, "preset": { "enum": [ "auto", "plain", "compact", "percent", "currency" ], "type": "string", "description": "Alias for the bare-string preset form." }, "suffix": { "type": "string", "maxLength": 20, "description": "Literal, e.g. \" per km²\"." }, "compact": { "type": "boolean", "description": "Compact notation: K/M/B/T (never SI \"G\")." }, "currency": { "type": "string", "default": "USD", "pattern": "^[A-Za-z]{3}$", "description": "ISO-4217 code, rendered with its Intl symbol (\"€\", \"CA$\"). Only valid with style \"currency\".\n" }, "decimals": { "type": "integer", "maximum": 6, "minimum": 0, "description": "Fraction digits. Min equals max, for uniform labels, unless `trim` is set." }, "grouping": { "type": "boolean", "default": true, "description": "Thousands separators." }, "significantDigits": { "type": "integer", "maximum": 6, "minimum": 1 } }, "description": "Number format for every choropleth surface: class labels, gradient ticks and value labels. Always pass an object, e.g. {\"preset\": \"compact\"}, never a bare string. Presets: `auto` (default, inferred from magnitude), `plain` (39,538,223), `compact` (39.5M), `percent` (the input is a FRACTION, so 0.42 prints as 42% and 0.423 as 42.3%, because the preset trims trailing zeros. An explicit {\"style\": \"percent\", \"decimals\": 1} keeps them and prints 42.0%. For data already in percent points use {\"suffix\": \"%\"}), `currency` ($39,538,223). Or combine options, e.g. {\"decimals\": 1, \"suffix\": \"M\"} or {\"style\": \"currency\", \"currency\": \"EUR\"}. {\"d3\": \"~s\"} is a raw d3-format escape hatch. Add \"locale\" for a non-US number style: \"de-DE\" (1.234,5 / 1,2 Mio.), \"fr-FR\" (1 234,5), \"es-ES\", \"it-IT\", \"pt-BR\", \"de-CH\" (1’234.5), \"en-IN\" (12,34,567 / 12L), \"nl-NL\", \"pl-PL\", \"sv-SE\"; it combines with presets and d3, and {\"locale\": \"de-DE\"} alone is the automatic format in that style. The result echoes the resolved format.", "additionalProperties": false }, "method": { "enum": [ "quantile", "equalInterval", "jenks", "pretty" ], "type": "string", "description": "Break method. Absent = round, publishable edges picked from the data (a constant step such as 0 · 10 · 20 · 30, or a 1-2-5 ladder such as 0 · 10K · 25K · 50K · 100K for skewed data), reported as `pretty`. quantile = equal number of regions per class, equalInterval = equal-width value intervals, jenks = natural breaks (minimal within-class variance), pretty = rounded human-readable edges. Additive-only enum: more methods may be added, none removed.\n" }, "noData": { "type": [ "boolean", "object" ], "properties": { "label": { "type": "string", "maxLength": 40, "minLength": 1 } }, "description": "Adds a \"No data\" row to the legend for regions without a value: true, or {\"label\": \"Not reported\"}. Off unless you send it. Send it whenever your data does not cover the whole map (the result reports how many regions have no value); without it those regions are drawn in a gray the legend does not explain. With full coverage the row is left out. A `nodata_low_contrast` warning means the default fill for those regions is hard to tell from the palette (gray palettes): send `noDataColor`.", "additionalProperties": false }, "values": { "type": "object", "description": "Region key to numeric value. Keys go through the matching rules described above. Two keys resolving to the same region count as two matched keys, and the later value wins.\n", "maxProperties": 5000, "minProperties": 1, "additionalProperties": { "type": "number" } }, "classes": { "type": "integer", "maximum": 9, "minimum": 2, "description": "Number of classes. Absent = suggested from the data (5 base, more for skewed distributions). Explicit counts are honored exactly, capped only by the number of unique values. Tied values can still collapse duplicate quantile edges, and a constant dataset collapses to one class. `dryRun` returns the breaks and effective class count that will actually be drawn.\n" }, "palette": { "enum": [ "gnbu", "bugn", "bupu", "orrd", "pubu", "pubugn", "purd", "rdpu", "ylgn", "ylgnbu", "ylorbr", "ylorrd", "blues", "greens", "greys", "oranges", "purples", "reds", "rdbu", "brbg", "spectral", "piyg", "prgn", "puor", "rdgy", "rdylbu" ], "type": "string", "description": "ColorBrewer palette id (the server matches case-insensitively). Absent = suggested: `rdbu` centered on `midpoint` when one is given (or `kind` is `change`); with no hints, `rdbu` centered on 0 when the values spread on both sides of zero; sequential blues otherwise. Sequential palettes suit one-directional data, and diverging palettes (rdbu, brbg, spectral, piyg, prgn, puor, rdgy, rdylbu) suit data around a midpoint.\n" }, "midpoint": { "type": "number", "description": "The meaningful center of the data: 0 for a change or balance, 100 for an index where 100 is the reference (EU27 = 100), 1 for a ratio. Gives a diverging palette with its neutral color on this value. Leave it out for one-directional data." }, "noDataColor": { "type": "string", "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$", "examples": [ "#1D4ED8" ], "description": "Fill for regions absent from `values`. Choropleth mode only. Overrides `style.defaultRegionColor` when both are set. When neither is set, the theme's region color is used if it stays apart from the palette (CIEDE2000 ≥ 12 from the lightest class, ≥ 8 from every class) or is transparent by design; otherwise a light, slightly theme-tinted gray that does and keeps the region borders visible, so missing data never reads as the lowest class or as the neutral of a diverging palette. Gray palettes can leave no such color: the theme color is then darkened and a `nodata_low_contrast` warning asks for an explicit `noDataColor`.\n" }, "legendEndLabels": { "type": "boolean", "description": "Steps legends: also print the two outer ends of the bar (ignored for groups and gradient legends). An end that the automatic breaks left open, or that the data reaches past, reads \"< 10\" / \"≥ 90\" rather than a round bound the data never reaches. Groups legends already print every range and gradients their ends, so only steps change. Default false.\n" } }, "description": "Numeric choropleth mode. Mutually exclusive with `categories` (one scale per map). `regions` composes with it as an override layer. If none of the keys in `values` match, the request fails even under `onUnmatched: warn`, since there is nothing to build a scale from. `type`, `classes`, `method` and `palette` are all optional: whatever you leave out is suggested from the data, and the resolved plan is reported in the result. Do send `kind` whenever you know what the numbers are, `midpoint` when they have a meaningful center, and a short `unit`: the values alone cannot tell 42% from 0.42 or a change from a level.", "additionalProperties": false }, "onUnmatched": { "enum": [ "warn", "error" ], "type": "string", "default": "warn", "description": "warn = render anyway (unmatched regions get the no-data fill) and report. error = 400 with per-key suggestions. Recommended for production pipelines: error. Exception: in choropleth mode, ZERO matched keys is a 400 even under warn. Region keys in `style.labels.hide` count too: a typo there is a 400 under error.\n" } }, "additionalProperties": false }