Ultimaps MCP

官方

将数据转化为地图图像：世界、国家、州、县和邮政编码的分区统计图、分类图和标记图。

访问 ultimaps.com试用此 MCP赞助

你可以用 Ultimaps MCP 做什么？

渲染分级统计图 — 请求按数值着色的地图，即可获得带图例和标签的分类PNG图片。
高亮特定区域 — 请求将指定州、县或邮政编码区域填充为自定义颜色的地图，例如“我们的运营区域”。
添加位置标记 — 在任何地图上绘制经纬度标记，并支持自定义标题、颜色和标签位置。
验证地图数据 — 进行试运行以检查哪些区域键匹配，获取拼写更正，并在渲染前查看分段值。
列出可用地图 — 询问187种地图（国家、州、县、邮政编码区域）中哪些可通过 list_maps 获取。
获取区域标识符 — 通过 get_map_regions 查找地图区域的确切键或名称，以便在渲染请求中使用。

文档

地图图像 API

数据输入，地图图像输出。一个 URL 即可将任何国家、州、县或邮政编码区域渲染为等值线图、分类图或标记图，输出为 PNG 格式。无需账户、无需密钥、无需在技术栈中集成地图库。

https://api.ultimaps.com/v1/renders?spec=%7B%22mapId%22%3A%22united-states%22%2C%22regions%22%3A%7B%22US-CA%22%3A%22%231D4ED8%22%2C%22US-TX%22%3A%22%23F59E0B%22%2C%22New%20York%22%3A%22%2310B981%22%7D%2C%22title%22%3A%7B%22text%22%3A%22Where%20we%20operate%22%7D%2C%22style%22%3A%7B%22labels%22%3A%7B%22show%22%3Atrue%7D%7D%2C%22output%22%3A%7B%22width%22%3A1200%7D%7D

这就是完整的请求。spec 参数是 URL 编码的 JSON，响应就是图像本身。

US map rendered by the Ultimaps API, every state labelled, with California, Texas and New York filled in

由左侧 URL 实时渲染，缓存 24 小时。

随处可用

URL 返回图像，因此它可以在 <img> 标签、README、Notion 页面或 Google Sheets 单元格中工作。

GET 或 POST

GET 支持所有功能，但将请求体限制在 6KB，并且始终渲染无密钥的 PNG，最大 1600px。将相同的 JSON 发送到 POST /v1/renders 可获得更大的请求体、用于更大画布的密钥，或使用 Pro 密钥获取 SVG。

之后可编辑

每张图像都带有 Link 标头，可在 Ultimaps Studio 中作为真实地图打开渲染结果。无密钥渲染对任何拥有链接的人开放。带密钥的渲染仅对登录该密钥工作区的人开放。

示例集

六个完整请求。每个请求都在 CI 中针对实时请求模式进行验证，因此您可以原样复制，替换 mapId 和值，然后直接使用。每张图像都是其旁边请求返回的响应，包含水印，基于免费无密钥层级。

高亮几个区域

最简单实用的请求。您指定区域并为每个区域指定颜色。其他所有内容使用地图默认设置。

{
  "mapId": "united-states",
  "regions": {
    "US-CA": "#1D4ED8",
    "US-TX": "#F59E0B",
    "New York": "#10B981"
  },
  "title": {
    "text": "Where we operate"
  },
  "style": {
    "labels": {
      "show": true
    }
  },
  "output": {
    "width": 1200
  }
}

curl https://api.ultimaps.com/v1/renders \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "regions": {
      "US-CA": "#1D4ED8",
      "US-TX": "#F59E0B",
      "New York": "#10B981"
    },
    "title": {
      "text": "Where we operate"
    },
    "style": {
      "labels": {
        "show": true
      }
    },
    "output": {
      "width": 1200
    }
  }' \
  -o map.png

Map of the United States titled "Where we operate", with California blue, Texas orange and New York green, every other state in the theme default and labelled with its abbreviation

美国地图，标题为“我们的运营区域”，加利福尼亚州为蓝色，德克萨斯州为橙色，纽约州为绿色，其他所有州使用主题默认颜色并标注缩写

区域键很灵活。“US-CA”、“California”和“CA”都指向同一区域。
颜色是十六进制字符串。您未指定的区域保持主题默认颜色。
“style.labels.show”会打印所有区域名称。无法仅标注您着色的区域。

在新标签页中打开此渲染

从数字生成等值线图

向 API 提供原始值，它会自动选择分类、颜色和图例。这是大多数人需要的请求。

{
  "mapId": "united-states",
  "choropleth": {
    "values": {
      "California": 39.5,
      "Texas": 30.5,
      "Florida": 22.6,
      "New York": 19.6,
      "Pennsylvania": 13,
      "Illinois": 12.5,
      "Ohio": 11.8,
      "Georgia": 11,
      "North Carolina": 10.8,
      "Michigan": 10
    },
    "type": "groups",
    "palette": "blues",
    "classes": 5,
    "method": "quantile",
    "noDataColor": "#EEEEEE",
    "format": {
      "decimals": 1,
      "suffix": "M"
    }
  },
  "legend": {
    "position": "left"
  },
  "title": {
    "text": "Population by state, 2025"
  },
  "style": {
    "labels": {
      "show": true,
      "content": "value"
    }
  },
  "output": {
    "width": 1600,
    "scale": 1
  }
}

curl https://api.ultimaps.com/v1/renders \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "choropleth": {
      "values": {
        "California": 39.5,
        "Texas": 30.5,
        "Florida": 22.6,
        "New York": 19.6,
        "Pennsylvania": 13,
        "Illinois": 12.5,
        "Ohio": 11.8,
        "Georgia": 11,
        "North Carolina": 10.8,
        "Michigan": 10
      },
      "type": "groups",
      "palette": "blues",
      "classes": 5,
      "method": "quantile",
      "noDataColor": "#EEEEEE",
      "format": {
        "decimals": 1,
        "suffix": "M"
      }
    },
    "legend": {
      "position": "left"
    },
    "title": {
      "text": "Population by state, 2025"
    },
    "style": {
      "labels": {
        "show": true,
        "content": "value"
      }
    },
    "output": {
      "width": 1600,
      "scale": 1
    }
  }' \
  -o map.png

Choropleth map of US state population in 2025, shaded across five blue quantile classes with the break labels in a legend and each value printed in millions on its state

2025 年美国各州人口等值线图，按五个蓝色分位数类别着色，图例中显示断点标签，每个州上以百万为单位打印数值

省略“type”、“classes”和“method”，API 会根据您的数据自动检测。
“palette”接受 26 种内置调色板中的任意一种。“noDataColor”为您的数据未覆盖的区域着色。
“format”控制图例中的断点标签，而非图像格式。

在新标签页中打开此渲染

标记

纬度和经度标记。标记可与所有其他功能组合，因此您可以将其放置在等值线图或普通地图上。

SVG 输出需要 Pro 密钥。在任何层级上省略“format”即可获得 PNG。

{
  "mapId": "united-states",
  "style": {
    "theme": "paper",
    "defaultRegionColor": "#F1F5F9"
  },
  "locations": [
    {
      "title": "Austin HQ",
      "lat": 30.2672,
      "lon": -97.7431,
      "color": "#1D4ED8"
    },
    {
      "title": "Denver",
      "lat": 39.7392,
      "lon": -104.9903,
      "labelPosition": "right"
    },
    {
      "title": "Seattle",
      "lat": 47.6062,
      "lon": -122.3321
    }
  ],
  "output": {
    "width": 1400,
    "format": "svg"
  }
}

curl https://api.ultimaps.com/v1/renders \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "style": {
      "theme": "paper",
      "defaultRegionColor": "#F1F5F9"
    },
    "locations": [
      {
        "title": "Austin HQ",
        "lat": 30.2672,
        "lon": -97.7431,
        "color": "#1D4ED8"
      },
      {
        "title": "Denver",
        "lat": 39.7392,
        "lon": -104.9903,
        "labelPosition": "right"
      },
      {
        "title": "Seattle",
        "lat": 47.6062,
        "lon": -122.3321
      }
    ],
    "output": {
      "width": 1400,
      "format": "svg"
    }
  }' \
  -o map.svg

Map of the United States on a pale theme with labelled pins on Austin, Denver and Seattle, the Austin pin in blue and the other two in the default red

显示为 PNG——请求要求的是 SVG。两种方式地图相同。

每个标记都有自己的颜色、标签位置和标签可见性。
标记按坐标放置。API 不进行地址地理编码。

SVG 需要 Pro 密钥。无密钥的 GET 路径仅返回 PNG。

在渲染前检查请求

试运行返回 JSON 而非图像：哪些键匹配、哪些未匹配、哪些被修正以及断点结果如何。不消耗配额。

{
  "mapId": "united-states",
  "choropleth": {
    "values": {
      "Calfornia": 39.5,
      "Texas": 30.5,
      "Florida": 22.6,
      "Atlantis": 1
    }
  },
  "dryRun": true
}

curl https://api.ultimaps.com/v1/renders \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "choropleth": {
      "values": {
        "Calfornia": 39.5,
        "Texas": 30.5,
        "Florida": 22.6,
        "Atlantis": 1
      }
    },
    "dryRun": true
  }'

拼写错误的“Calfornia”会被修正为 California。“Atlantis”返回未匹配。
在连接数据时使用此功能，然后关闭“dryRun”。

打开此返回的试运行 JSON

对无效键报错而非猜测

默认情况下，未匹配的键会被跳过。将“onUnmatched”设置为“error”，API 将返回 400 错误及逐键建议，这在定时任务中正是您需要的。

{
  "mapId": "united-states",
  "choropleth": {
    "values": {
      "California": 39.5,
      "Texassss": 30.5,
      "Atlantis": 1
    }
  },
  "onUnmatched": "error"
}

curl https://api.ultimaps.com/v1/renders \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "choropleth": {
      "values": {
        "California": 39.5,
        "Texassss": 30.5,
        "Atlantis": 1
      }
    },
    "onUnmatched": "error"
  }' \
  -o map.png

400 错误是 RFC 9457 问题文档。根据“code”而非消息进行分支处理。

打开此返回的 400 错误

完整字段参考，包括全部 26 种调色板、四种断点方法、主题、附加图层和数字格式：API 参考。

可渲染的地图

187 张地图，从世界和大陆地图到美国县和邮政编码区域。mapId 是地图在本站点的标识，发布后永不更改。

united-states-canada france-departments india europe canada united-states united-arab-emirates united-kingdom-counties world

密钥与限制

密钥可提高速率限制和画布尺寸。Pro 密钥可移除水印并解锁 SVG。在 Studio 的工作区下创建，然后选择 API。密钥仅显示一次。

curl https://api.ultimaps.com/v1/renders \
  -H "Authorization: Bearer $ULTIMAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "choropleth": {
      "values": {
        "California": 39.5,
        "Texas": 30.5,
        "Florida": 22.6,
        "New York": 19.6,
        "Pennsylvania": 13,
        "Illinois": 12.5,
        "Ohio": 11.8,
        "Georgia": 11,
        "North Carolina": 10.8,
        "Michigan": 10
      },
      "type": "groups",
      "palette": "blues",
      "classes": 5,
      "method": "quantile",
      "noDataColor": "#EEEEEE",
      "format": {
        "decimals": 1,
        "suffix": "M"
      }
    },
    "legend": {
      "position": "left"
    },
    "title": {
      "text": "Population by state, 2025"
    },
    "style": {
      "labels": {
        "show": true,
        "content": "value"
      }
    },
    "output": {
      "width": 1600,
      "scale": 1
    }
  }' \
  -o map.png

层级	认证	格式	署名	画布	速率限制	每月
无密钥	无	PNG	完整水印	≤ 1600 px，比例 1	每 IP 每小时 30 次，突发每分钟 5 次	无每月上限
免费密钥	Bearer um_live_…	PNG	完整水印	≤ 1600 px，比例 ≤ 2	每分钟 10 次，每天 50 次	500 次渲染
Pro 密钥	Bearer um_live_…	PNG、SVG	无	≤ 4000 px，比例 ≤ 4	每分钟 30 次，每天 1,000 次	5,000 次渲染

每月配额是计费状态，返回 402，不可重试。速率和并发限制返回 429 及 Retry-After。试运行从不消耗配额。查看 GET /v1/usage 了解您的使用情况。

从 Claude、Codex 或任何 MCP 客户端使用

在聊天中请求地图，图像会直接返回到对话中。@ultimaps/mcp 是此 API 以 MCP 工具形式通过 stdio 提供，无需账户：render_map、list_maps 和 get_map_regions。

claude mcp add ultimaps -- npx -y @ultimaps/mcp
codex mcp add ultimaps -- npx -y @ultimaps/mcp

读取配置文件的客户端接受相同的两个值。这是 claude_desktop_config.json。

{
  "mcpServers": {
    "ultimaps": {
      "command": "npx",
      "args": ["-y", "@ultimaps/mcp"],
      "env": { "ULTIMAPS_API_KEY": "" }
    }
  }
}

将 ULTIMAPS_API_KEY 留空以使用无密钥层级，限制与上表相同，或填写以使用您计划的配额和输出。

不在 v1 中

v1 渲染图像。它不提供以下任何功能：

发布交互式或可嵌入地图
PDF 输出
将地址地理编码为坐标
读取地图背后的几何数据

如果您需要其中一项，请告诉我们，我们会让您知道何时可用。人们在这里提出的需求就是我们接下来要构建的。

参考

API 参考

每个端点和字段，均针对运行中的 API 实时验证。

错误代码

每个代码、其 HTTP 状态以及是否应重试。

openapi.json

OpenAPI 3.1 契约。可从中生成客户端。

llms-full.txt

整个 API 以纯文本文件形式提供，供编码代理使用。

@ultimaps/mcp

MCP 服务器。三个工具，stdio，无需账户。

常见问题

有等值线图 API 吗？

有，这正是此 API 的主要功能。提交一组区域键和数字，即可获得一张已分类、着色、带图例的 PNG 地图。除非您自行设置，否则 API 会根据您的数据选择断点方法、分类数量和调色板。

如何从 URL 生成地图图像？

将您的请求 JSON 放入 GET /v1/renders 的 spec 查询参数中，响应就是 PNG 本身。该 URL 可在 img 标签、Markdown 图像、Notion 图像块或 Google Sheets 的 IMAGE() 公式中使用，无需密钥和账户。

我可以在没有 API 密钥的情况下使用地图图像 API 吗？

可以。无密钥层级可渲染最大 1600×1600 像素的 PNG，每 IP 每小时 30 次渲染，带 Ultimaps 水印。密钥可提高限制，Pro 密钥可移除水印并添加 SVG。

这是县级地图 API 吗？我可以从中获取县边界吗？

它可以将县级地图渲染为图像，包括全部 3,143 个美国县，但不提供边界几何数据。如果您需要 GeoJSON 或 shapefile 自行处理，请改用 Census TIGER 或 Natural Earth。此 API 返回图片。

它能进行地址地理编码吗？

不能。标记按纬度和经度放置，区域颜色按区域键或名称匹配。地理编码是 Studio 的功能，而非 API 的功能。

有 MCP 服务器吗？

有。在 Claude Code、Codex、Claude Desktop、Cursor、VS Code 或任何其他 MCP 客户端中安装 @ultimaps/mcp，它即可通过 stdio 提供 render_map、list_maps 和 get_map_regions 工具。它运行在 Node.js 20 或更高版本上，无需账户，并在您设置 ULTIMAPS_API_KEY 时读取它。

我可以获取 SVG 而不是 PNG 吗？

可以，使用 Pro 密钥。将 output.format 设置为 svg。无密钥和免费密钥返回 PNG。

如果我的区域名称不匹配会怎样？

键会不区分大小写地与区域代码、标题、常见别名和规范化标题进行匹配，因此 US-CA、California 和 CA 都指向同一区域，无歧义的拼写错误会被修正并报告。默认情况下，未匹配的键会被跳过并在响应标头中报告。将 onUnmatched 设置为 error，请求将失败并返回逐键建议。

如何将地图放入 GitHub README？

使用无密钥的 GET URL 作为 Markdown 图像。GitHub 会通过 Camo 代理它，由于 API 发送 24 小时缓存标头，图像每天刷新而非冻结。

我可以在服务器端渲染地图吗？

可以。每次渲染都在我们的服务器上完成，因此您的技术栈中不需要浏览器、无头 Chrome 或地图库。一次 HTTP 调用即可返回完成的图像。