Ultimaps MCP

官方

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

访问 ultimaps.com

你可以用 Ultimaps MCP 做什么？

从数据渲染地图 — 让助手将区域值转换为带图例和标题的彩色分级统计地图图像。
高亮特定区域 — 请求生成一张地图，其中指定的州、县或国家/地区用选定的十六进制颜色填充。
按坐标放置图钉 — 请求在给定的纬度和经度处放置带标签的图钉，可选择与分级统计地图结合使用。
列出可用地图 — 让助手查询存在哪些地图 ID，例如 united-states 或 europe。
渲染前检查区域键 — 运行试运行，查看哪些区域名称匹配成功、哪些被修正、哪些失败。
查询地图的区域 — 询问给定地图包含哪些区域，以便为渲染构建有效的键。

文档

地图图像 API

数据输入，地图图像输出。一个 URL 即可将任意国家、州、县或 ZIP 区域渲染为分级统计图、分类图或标记图，输出为 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 支持所有功能，但 spec 上限为 6KB，且始终渲染无密钥 PNG，最大 1600px。将相同的 JSON 发送到 POST /v1/renders 可获得更大的请求体、使用密钥获得更大的画布，或使用 Pro 密钥获得 SVG。

之后可编辑

每张图像都带有一个 Link 响应头，可在 Ultimaps Studio 中将渲染结果作为真实地图打开。无密钥渲染对任何持有链接的人开放。有密钥的渲染仅对该密钥所属工作区的已登录用户开放。

示例集

六个完整请求。每一个都在 CI 中针对实时请求 schema 进行了验证，因此你可以直接复制、替换 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 labeled with its abbreviation

美国地图，标题为“Where we operate”，加利福尼亚为蓝色、德克萨斯为橙色、纽约为绿色，其余各州使用主题默认色并标注缩写

区域键灵活。 “US-CA”、“California” 和 “CA” 都能匹配到同一区域。
颜色为十六进制字符串。未指定的区域保持主题默认色。
“style.labels.show” 打印所有区域名称。若要让部分区域不显示标签，将其键列在 “style.labels.hide” 中。

在新标签页中打开此渲染

基于数值的分级统计图

向 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",
    "noData": true,
    "format": {
      "decimals": 1,
      "suffix": "M"
    }
  },
  "legend": {
    "position": "left",
    "title": "Population (millions)"
  },
  "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",
      "noData": true,
      "format": {
        "decimals": 1,
        "suffix": "M"
      }
    },
    "legend": {
      "position": "left",
      "title": "Population (millions)"
    },
    "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” 为数据未覆盖的区域着色，“noData” 在图例中为其添加一行“无数据”。
“legend.title” 为颜色所度量的内容命名。每个数据图例都应设置一个。
“format” 控制数字在图例和地图上的显示方式，而非图像格式。
此处 “style.labels.content” 为 “value”。“name_value” 会在州名下方打印数值。

在新标签页中打开此渲染

标记点

经纬度标记。标记可与其他所有功能组合使用，因此你可以将它们叠加在分级统计图或普通地图上。

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 labeled 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 参考。

可渲染的地图

189 张地图，从世界地图和大洲地图到美国县和 ZIP 区域。mapId 是地图在本站上的 slug，一旦发布便不会更改。

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

密钥与限制

密钥可提高速率限制和画布尺寸。Pro 密钥移除水印并解锁 SVG。在 Studio 的 Workspace 下创建，然后进入 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",
      "noData": true,
      "format": {
        "decimals": 1,
        "suffix": "M"
      }
    },
    "legend": {
      "position": "left",
      "title": "Population (millions)"
    },
    "title": {
      "text": "Population by state, 2025"
    },
    "style": {
      "labels": {
        "show": true,
        "content": "value"
      }
    },
    "output": {
      "width": 1600,
      "scale": 1
    }
  }' \
  -o map.png

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

月度配额是一种计费状态，返回 402，绝不可重试。速率和并发限制返回 429 并附带 Retry-After。试运行从不消耗配额。查看 GET /v1/usage 了解当前状态。

从 ChatGPT、Claude 或任意 MCP 客户端使用

在 ChatGPT、Claude、Cursor 或任意 MCP 客户端中使用此 API，即可在对话中获取地图。通过 URL 添加 https://api.ultimaps.com/mcp，或在你的电脑上运行 @ultimaps/mcp 包。两者均无需账户。

设置 Ultimaps MCP 服务器

v1 不包含的功能

v1 渲染图像。不包含以下任何功能：

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

如果你需要其中某项功能，请告诉我们具体是哪项，我们会在功能上线时通知你。用户在这里提出的需求就是我们接下来要构建的内容。

参考

API 参考

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

错误码

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

openapi.json

OpenAPI 3.1 契约。可据此生成客户端。

llms-full.txt

整个 API 以单个纯文本文件呈现，供编码代理使用。

MCP 服务器

通过 URL 添加 https://api.ultimaps.com/mcp，或在本地运行 @ultimaps/mcp。无需账户。

常见问题

有分级统计图 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 服务器吗？

有。在 ChatGPT、Claude 或任意 MCP 客户端中通过 URL 添加 https://api.ultimaps.com/mcp，或在本地运行 @ultimaps/mcp 包，你的助手即可使用 render_map、list_maps 和 get_map_regions，无需账户。各客户端的设置步骤见 ultimaps.com/mcp/。

可以获得 SVG 而非 PNG 吗？

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

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

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

如何将地图放入 GitHub README？

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

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

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