Ultimaps MCP

API Hình ảnh Bản đồ

Dữ liệu vào, hình ảnh bản đồ ra. Một URL duy nhất kết xuất bản đồ choropleth, phân loại hoặc ghim của bất kỳ quốc gia, tiểu bang, quận hoặc khu vực 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 hệ thống 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 kết xuất trực tiếp bởi URL bên trái, được lưu trong bộ nhớ đệm 24 giờ.

Dùng được ở mọi nơi

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

GET hoặc POST

GET hỗ trợ mọi tính năng nhưng giới hạn spec ở 6KB, và luôn kết xuất PNG không cần khóa tối đa 1600px. Gửi cùng JSON đó đến POST /v1/renders để có payload lớn hơn, dùng khóa để có khung vẽ lớn hơn, hoặc khóa Pro để có SVG.

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

Mỗi hình ảnh mang theo header Link mở bản kết xuất trong Ultimaps Studio dưới dạng bản đồ thực sự. 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ổ tay công thức

Sáu yêu cầu hoàn chỉnh. Mỗi yêu cầu đều được kiểm chứng với schema yêu cầu trực tiếp trong CI, nên bạn có thể sao chép nguyên văn, 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 miễn phí không cần khóa.

Làm nổi bật một vài vùng

Yêu cầu hữu ích đơn giản nhất. Bạn đặt tên các vùng và gán cho mỗi vùng một màu. Mọi thứ khác 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 đề "Where we operate", 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 dùng mặc định của theme và được gắn nhãn bằng chữ viết tắt

• Khóa vùng rất linh hoạt. "US-CA", "California" và "CA" đều trỏ đến cùng một vùng.
• Màu là chuỗi hex. Các vùng bạn bỏ qua sẽ giữ mặc định của theme.
• "style.labels.show" in tên mọi vùng. Để một số vùng không có nhãn, liệt kê khóa của chúng trong "style.labels.hide".

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

Choropleth từ số liệu

Đưa giá trị thô cho API và nó sẽ tự chọn các 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",
    "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

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

• Bỏ qua "type", "classes" và "method" thì API sẽ 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 26 bảng màu tích hợp. "noDataColor" tô các vùng mà dữ liệu của bạn không bao phủ, và "noData" thêm một dòng "No data" cho chúng vào chú giải.
• "legend.title" đặt tên cho đại lượng mà màu sắc thể hiện. Hãy đặt cho mỗi chú giải dữ liệu một tiêu đề.
• "format" kiểm soát cách in số trong chú giải và trên bản đồ, không phải định dạng hình ảnh.
• "style.labels.content" ở đây là "value". "name_value" in tên tiểu bang kèm số bên dưới.

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

Ghim

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

Đầu ra SVG cần khóa Pro. Bỏ "format" để có 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 đòi SVG. Bản đồ vẫn như nhau.

• Mỗi ghim có màu riêng, phía 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ỉ thành tọa độ.

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, những gì được sửa và các ngưỡng cho ra kết quả gì. Không tốn hạn mức.

{
  "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 trả về đã sửa thành California. "Atlantis" trả về không khớp.
• Dùng tính năng này khi bạn đang kết nối dữ liệu, sau đó tắt "dryRun".

Mở JSON chạy thử mà yêu cầu này trả về

Báo lỗi khi khóa sai thay vì đoán

Mặc định các khóa không khớp sẽ bị bỏ qua. Đặt "onUnmatched" thành "error" và API trả về 400 kèm gợi ý cho từng khóa, đây là điều bạn muốn trong một tác vụ theo lịch.

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

• Lỗi 400 là một tài liệu vấn đề theo RFC 9457. Hãy rẽ nhánh theo "code", không theo thông điệp.

Mở lỗi 400 mà yêu cầu này trả về

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

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

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

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

Khóa và giới hạn

Khóa giúp tăng giới hạn tốc độ và kích thước khung vẽ. Khóa Pro loại bỏ watermark và mở khóa SVG. Tạo khóa trong Studio tại Workspace, rồi đến 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",
      "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

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

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

Từ ChatGPT, Claude hoặc bất kỳ ứng dụng MCP nào

Dùng API này từ ChatGPT, Claude, Cursor hoặc bất kỳ ứng dụng MCP nào và nhận bản đồ ngay trong cuộc trò chuyện. Thêm https://api.ultimaps.com/mcp bằng URL, hoặc chạy gói @ultimaps/mcp trên máy của bạn. Cả hai đều không cần tài khoản.

Thiết lập máy chủ Ultimaps MCP

Không có trong v1

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

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

Nếu bạn cần một trong những tính năng này, hãy cho chúng tôi biết bạn cần cái nào và chúng tôi sẽ thông báo khi nó có sẵn. Những gì mọi người yêu cầu ở đây chính 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à liệu có nên thử lại hay không.

openapi.json

Hợp đồng OpenAPI 3.1. Tạo client từ nó.

llms-full.txt

Toàn bộ API trong một tệp văn bản thuần cho các tác nhân lập trình.

Máy chủ MCP

Thêm https://api.ultimaps.com/mcp bằng URL, hoặc chạy @ultimaps/mcp cục bộ. Không cần tài khoản.

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

Có API choropleth không?

Có, đó là chức năng chính của API này. Gửi một tập hợp khóa vùng và số liệu và bạn nhận lại một bản đồ đã được phân lớp, tô màu, có chú giải dưới dạng PNG. API tự chọn phương pháp chia ngưỡng, 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 thế nào để tạo hình ảnh bản đồ từ một URL?

Đặt JSON yêu cầu của bạn vào 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ể 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 tối đa 1600 x 1600 pixel với 30 lần kết xuất mỗi giờ mỗi IP, kèm watermark Ultimaps. Khóa giúp tăng giới hạn, và khóa Pro loại bỏ 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 cả 3.143 quận của Hoa Kỳ, nhưng nó không cung cấp hình học ranh giới. Nếu bạn cần GeoJSON hoặc shapefile để tự xử lý, hãy dùng Census TIGER hoặc Natural Earth thay thế. 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 vùng được khớp theo khóa hoặc tên vùng. 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ó. Thêm https://api.ultimaps.com/mcp bằng URL trong ChatGPT, Claude hoặc bất kỳ ứng dụng MCP nào, hoặc chạy gói @ultimaps/mcp cục bộ, và trợ lý của bạn sẽ có render_map, list_maps và get_map_regions mà không cần tài khoản. Các bước thiết lập cho từng ứng dụng có tại ultimaps.com/mcp/.

Tôi có thể lấy 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 vùng 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ã vùng, tiêu đề, bí danh phổ biến và tiêu đề đã chuẩn hóa, nên US-CA, California và CA đều trỏ đến cùng một vùng, và các lỗi chính tả không mơ hồ sẽ được sửa và báo cáo. Mặc định các khóa không khớp sẽ bị bỏ qua và được báo cáo trong header phản hồi. Đặt onUnmatched thành error và yêu cầu sẽ thất bại kèm gợi ý cho từng khóa.

Làm thế nào để đưa bản đồ vào README GitHub?

Dùng URL GET không cần khóa làm hình ảnh markdown. GitHub chuyển tiếp nó qua Camo, và vì API gửi header bộ nhớ đệm 24 giờ nên hình ảnh làm mới hàng ngày thay vì bị đóng băng.

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

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