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

美國地圖，標題為「Where we operate」，加州為藍色、德州為橘色、紐約為綠色，其他各州使用主題預設色並標示其縮寫

區域金鑰很彈性。「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 是地圖在此網站上的 slug，一旦發布就永遠不會變更。

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

金鑰與限制

金鑰可提高速率限制和畫布大小。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",
      "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 x 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 呼叫即可回傳完成的影像。