Ultimaps MCP

API Bản đồ hình ảnh

Dữ liệu đầu vào, hình ảnh bản đồ đầu ra. Một URL hiển thị bản đồ choropleth, danh mục hoặc bản đồ ghim của bất kỳ quốc gia, tiểu bang, quận hoặc khu vực mã ZIP nào dưới dạng PNG. Không cần tài khoản, không cần khóa, không cần thư viện bản đồ trong stack của bạn.

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

Đó là toàn bộ yêu cầu. Tham số spec là JSON được mã hóa URL và phản hồi chính là hình ảnh.

Được hiển thị trực tiếp bởi URL ở bên trái, được lưu trong bộ nhớ đệm trong 24 giờ.

Tích hợp ở bất cứ đâu

URL trả về hình ảnh, vì vậy nó hoạt động trong thẻ <img>, README, trang Notion hoặc ô Google Sheets.

GET hoặc POST

GET nhận mọi tính năng nhưng giới hạn spec ở 6KB và luôn hiển thị PNG không cần khóa lên đến 1600px. Gửi cùng JSON đến POST /v1/renders để có payload lớn hơn, khóa cho canvas lớn hơn hoặc khóa Pro cho SVG.

Có thể chỉnh sửa sau đó

Mọi hình ảnh đều mang tiêu đề Link mở bản kết xuất trong Ultimaps Studio dưới dạng bản đồ thực. Bản kết xuất không cần khóa mở cho bất kỳ ai có liên kết. Bản kết xuất có khóa chỉ mở cho người đã đăng nhập vào workspace của khóa đó.

Sách nấu ăn

Sáu yêu cầu hoàn chỉnh. Mọi yêu cầu đều được xác thực với lược đồ yêu cầu trực tiếp trong CI, vì vậy bạn có thể sao chép chúng nguyên trạng, thay mapId và các giá trị rồi chạy. Mỗi hình ảnh là phản hồi mà yêu cầu bên cạnh trả về, bao gồm cả watermark, trên gói không cần khóa miễn phí.

Làm nổi bật một vài khu vực

Yêu cầu hữu ích đơn giản nhất. Bạn đặt tên các khu vực và gán màu cho từng khu vực. Mọi thứ khác sử dụng mặc định của bản đồ.

{
  "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

Bản đồ Hoa Kỳ có tiêu đề "Nơi chúng tôi hoạt động", với California màu xanh dương, Texas màu cam và New York màu xanh lá, mọi tiểu bang khác theo chủ đề mặc định và được gắn nhãn bằng chữ viết tắt

• Khóa khu vực linh hoạt. "US-CA", "California" và "CA" đều truy cập cùng một khu vực.
• Màu sắc là chuỗi hex. Các khu vực bạn bỏ qua giữ chủ đề mặc định.
• "style.labels.show" in tên mọi khu vực. Không có cách nào để chỉ gắn nhãn các khu vực bạn đã tô màu.

Mở bản kết xuất này trong tab mới

Choropleth từ số liệu

Cung cấp giá trị thô cho API và nó tự chọn lớp, màu sắc và chú giải. Đây là yêu cầu mà hầu hết mọi người muốn.

{
  "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

Bản đồ choropleth về dân số tiểu bang Hoa Kỳ năm 2025, được tô bóng qua năm lớp quantile màu xanh dương với nhãn phân chia trong chú giải và mỗi giá trị được in bằng triệu trên tiểu bang của nó

• Bỏ qua "type", "classes" và "method" và API tự phát hiện chúng từ dữ liệu của bạn.
• "palette" nhận bất kỳ bảng màu nào trong số 26 bảng màu tích hợp. "noDataColor" tô màu các khu vực mà dữ liệu của bạn không bao phủ.
• "format" kiểm soát nhãn phân chia trong chú giải, không phải định dạng hình ảnh.

Mở bản kết xuất này trong tab mới

Ghim

Điểm đánh dấu vĩ độ và kinh độ. Ghim kết hợp với mọi thứ khác, vì vậy bạn có thể đặt chúng trên bản đồ choropleth hoặc bản đồ trơn.

Đầu ra SVG cần khóa Pro. Bỏ "format" để nhận PNG trên mọi gói.

{
  "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

Hiển thị dưới dạng PNG — yêu cầu yêu cầu SVG. Cùng một bản đồ trong cả hai trường hợp.

• Mỗi ghim có màu sắc, vị trí nhãn và khả năng hiển thị nhãn riêng.
• Ghim được đặt theo tọa độ. API không mã hóa địa chỉ.

SVG cần khóa Pro. Đường dẫn GET không cần khóa chỉ trả về PNG.

Kiểm tra yêu cầu trước khi kết xuất

Chạy thử trả về JSON thay vì hình ảnh: khóa nào của bạn khớp, khóa nào không, điều gì đã được sửa và các phân chia trông như thế nào. Không tốn quota.

{
  "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
  }'

• Lỗi chính tả "Calfornia" được sửa thành California. "Atlantis" trả về không khớp.
• Sử dụng tính năng này khi bạn kết nối dữ liệu, sau đó tắt "dryRun".

Mở JSON chạy thử mà điều này trả về

Thất bại với khóa sai thay vì đoán

Theo mặc định, các khóa không khớp bị bỏ qua. Đặt "onUnmatched" thành "error" và API trả về 400 với gợi ý cho từng khóa, điều bạn muốn trong công việc theo lịch trình.

{
  "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 là tài liệu vấn đề RFC 9457. Phân nhánh theo "code", không phải theo thông báo.

Mở 400 mà điều này trả về

Tham chiếu trường đầy đủ, bao gồm tất cả 26 bảng màu, bốn phương pháp phân chia, chủ đề, lớp bổ sung và định dạng số: tham chiếu API.

Bản đồ bạn có thể kết xuất

187 bản đồ, từ bản đồ thế giới và lục địa đến các quận của Hoa Kỳ và khu vực mã ZIP. mapId là slug của bản đồ trên trang web này và không bao giờ thay đổi sau khi được xuất bản.

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

Khóa và giới hạn

Khóa tăng giới hạn tốc độ và kích thước canvas. Khóa Pro xóa watermark và mở khóa SVG. Tạo một khóa trong Studio dưới Workspace, sau đó API. Khóa chỉ được hiển thị một lần.

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

Gói	Xác thực	Định dạng	Ghi công	Canvas	Giới hạn tốc độ	Hàng tháng
Không cần khóa	không có	PNG	watermark đầy đủ	≤ 1600 px, tỷ lệ 1	30/giờ mỗi IP, burst 5/phút	không có giới hạn hàng tháng
Khóa miễn phí	Bearer um_live_…	PNG	watermark đầy đủ	≤ 1600 px, tỷ lệ ≤ 2	10/phút, 50/ngày	500 bản kết xuất
Khóa Pro	Bearer um_live_…	PNG, SVG	không có	≤ 4000 px, tỷ lệ ≤ 4	30/phút, 1.000/ngày	5.000 bản kết xuất

Quota hàng tháng là trạng thái thanh toán và trả về 402, không bao giờ thử lại. Giới hạn tốc độ và đồng thời trả về 429 với Retry-After. Chạy thử không bao giờ tiêu tốn quota. Kiểm tra GET /v1/usage để biết vị trí của bạn.

Từ Claude, Codex hoặc bất kỳ máy khách MCP nào

Yêu cầu bản đồ trong cuộc trò chuyện và hình ảnh sẽ trở lại trong cuộc trò chuyện. @ultimaps/mcp là API này dưới dạng công cụ MCP qua stdio, không cần tài khoản: render_map, list_maps và get_map_regions.

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

Các máy khách đọc tệp cấu hình nhận cùng hai giá trị. Đây là claude_desktop_config.json.

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

Để trống ULTIMAPS_API_KEY cho gói không cần khóa, cùng giới hạn như bảng trên, hoặc điền vào cho quota và đầu ra của gói bạn.

Không có trong v1

v1 kết xuất hình ảnh. Nó không thực hiện bất kỳ điều nào sau đây:

• Xuất bản bản đồ tương tác hoặc nhúng
• Đầu ra PDF
• Mã hóa địa chỉ thành tọa độ
• Đọc lại hình học đằng sau bản đồ

Nếu bạn cần một trong những điều này, hãy cho chúng tôi biết và chúng tôi sẽ thông báo khi nó tồn tại. Những gì mọi người yêu cầu ở đây là những gì chúng tôi xây dựng tiếp theo.

Tham chiếu

Tham chiếu API

Mọi endpoint và trường, trực tiếp với API đang chạy.

Mã lỗi

Mọi mã, trạng thái HTTP của nó và có nên thử lại hay không.

openapi.json

Hợp đồng OpenAPI 3.1. Tạo máy khách từ nó.

llms-full.txt

Toàn bộ API dưới dạng một tệp văn bản thuần túy cho các tác nhân mã hóa.

@ultimaps/mcp

Máy chủ MCP. Ba công cụ, stdio, không cần tài khoản.

Câu hỏi thường gặp

Có API choropleth không?

Có, đó là điều chính mà API này làm. Đăng một tập hợp khóa khu vực và số liệu và bạn nhận được bản đồ được phân loại, tô màu, có chú giải dưới dạng PNG. API tự chọn phương pháp phân chia, số lớp và bảng màu từ dữ liệu của bạn trừ khi bạn tự đặt chúng.

Làm cách nào để tạo hình ảnh bản đồ từ URL?

Đặt JSON yêu cầu của bạn trong tham số truy vấn spec của GET /v1/renders và phản hồi chính là PNG. URL đó hoạt động trong thẻ img, hình ảnh markdown, khối hình ảnh Notion hoặc công thức IMAGE() của Google Sheets, không cần khóa và không cần tài khoản.

Tôi có thể sử dụng API hình ảnh bản đồ mà không cần khóa API không?

Có. Gói không cần khóa kết xuất PNG lên đến 1600 x 1600 pixel với 30 bản kết xuất mỗi giờ mỗi IP, có watermark Ultimaps. Khóa tăng giới hạn và khóa Pro xóa watermark và thêm SVG.

Đây có phải là API bản đồ quận không? Tôi có thể lấy ranh giới quận từ nó không?

Nó kết xuất bản đồ quận dưới dạng hình ảnh, bao gồm tất cả 3.143 quận của Hoa Kỳ, nhưng không phục vụ hình học ranh giới. Nếu bạn cần GeoJSON hoặc shapefile để tự xử lý, hãy sử dụng Census TIGER hoặc Natural Earth. API này trả về hình ảnh.

Nó có mã hóa địa chỉ không?

Không. Ghim được đặt theo vĩ độ và kinh độ, và màu khu vực được khớp theo khóa hoặc tên khu vực. Mã hóa địa chỉ là tính năng của Studio, không phải của API.

Có máy chủ MCP không?

Có. Cài đặt @ultimaps/mcp trong Claude Code, Codex, Claude Desktop, Cursor, VS Code hoặc bất kỳ máy khách MCP nào khác và nó hiển thị render_map, list_maps và get_map_regions qua stdio. Nó chạy trên Node.js 20 trở lên, không cần tài khoản và đọc ULTIMAPS_API_KEY khi bạn đặt một khóa.

Tôi có thể nhận SVG thay vì PNG không?

Có, với khóa Pro. Đặt output.format thành svg. Khóa không cần khóa và khóa miễn phí trả về PNG.

Điều gì xảy ra nếu tên khu vực của tôi không khớp?

Khóa được khớp không phân biệt chữ hoa chữ thường với mã khu vực, tiêu đề, bí danh phổ biến và tiêu đề chuẩn hóa, vì vậy US-CA, California và CA đều truy cập cùng một khu vực và các lỗi chính tả không mơ hồ được sửa và báo cáo. Theo mặc định, các khóa không khớp bị bỏ qua và được báo cáo trong tiêu đề phản hồi. Đặt onUnmatched thành error và yêu cầu thất bại với gợi ý cho từng khóa.

Làm cách nào để đặt bản đồ trong README GitHub?

Sử dụng URL GET không cần khóa dưới dạng hình ảnh markdown. GitHub ủy quyền nó qua Camo và vì API gửi tiêu đề bộ nhớ đệm 24 giờ, hình ảnh làm mới hàng ngày thay vì đóng băng.

Tôi có thể kết xuất bản đồ phía máy chủ không?

Có. Mọi bản kết xuất diễn ra trên máy chủ của chúng tôi, vì vậy không có trình duyệt, không có Chrome headless và không có thư viện bản đồ trong stack của bạn. Một lệnh gọi HTTP duy nhất trả về hình ảnh hoàn chỉnh.