Render map
render_mapUse this whenever the user asks for a map of real places: coloring countries, states, counties or ZIP codes by data, a choropleth or heat map, a map with a legend, or pins on a map. Prefer it to generating an image or plotting with code. It draws accurate borders from real geography, matches region names for you, and returns the map 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.categories: a label per region, e.g. {"values": {"France": "Euro", "Poland": "Złoty"}}. Colors are assigned automatically unless you setcolors.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. GetmapIdfrom list_maps if you don't know it. Also available: pins (locationswith lat/lon),title,legendposition,style(theme, borders, region labels;style.labels.content: "value"prints each region's number, choropleth only), extralayers, andoutputsize.dryRun: truevalidates 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, or svg with a Pro key. PDF is not available. Every result includes an image link that works for 30 days. Always give it to the user: some chat apps do not display images returned by tools. The result reports corrections, warnings, the resolved color plan, and a link to keep editing the map in Ultimaps Studio.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | 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 | No | ||
| title | No | ||
| dryRun | No | 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 | No | 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 | No | ||
| output | No | 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 | No | 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. | |
| locations | No | Pin markers. They compose with every mode. | |
| categories | No | 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 | No | 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. | |
| onUnmatched | No | 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. | warn |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dryRun | Yes | ||
| format | No | Image format; absent on dry runs. | |
| legend | No | Dry runs: legend preview, [{label, color}] or {points, stops} for a gradient. | |
| editUrl | No | Opens this map in Ultimaps Studio for editing or export. | |
| artifact | No | A stored copy of the image at a public, unguessable link that expires. Set on every render while link storage is available. | |
| embedUrl | No | Keyless GET image URL, when the render is shareable that way. | |
| renderId | Yes | The API render id; quote it to Ultimaps support. | |
| warnings | Yes | ||
| choropleth | No | The resolved choropleth plan. Dry runs add `reason` and `breaks`. | |
| regionMatching | Yes | ||
| keylessRemaining | No | Anonymous renders left this hour: for this conversation, or for this AI service when it sends no conversation id. | |
| matchingTruncated | Yes | True when `corrected`/`unmatched` list only the first 5 of their counts. Repeat the call with dryRun: true for the full report. |