Ultimaps MCP

官方

將資料轉換為地圖影像：世界、國家、州、縣和郵遞區號的等值區域圖、類別圖和標記地圖。

造訪 ultimaps.com

你可以用 Ultimaps MCP 做什麼？

從資料渲染地圖 — 請你的助理將區域數值轉換成帶有圖例和標題的彩色分級統計地圖影像。
突顯特定區域 — 要求一張以指定十六進位色碼填滿具名州、郡或國家的地圖。
依座標放置圖釘 — 要求在給定的緯度和經度放置附標籤的圖釘，並可選擇與分級統計地圖合併。
列出可用的地圖 — 讓你的助理查詢有哪些地圖 ID 存在，例如 united-states 或 europe。
渲染前檢查區域鍵 — 執行試運行，查看哪些區域名稱相符、哪些已被修正，以及哪些失敗。
查詢地圖的區域 — 詢問指定地圖包含哪些區域，以便為渲染建立有效的鍵。

文件

地圖圖片 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 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」會在圖例中為這些區域新增一列「No data」。
「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 張地圖，從世界與各大洲地圖，到美國各郡與郵遞區號區域。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 x 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 呼叫即可回傳完成的圖片。