Ultimaps MCP

API Gambar Peta

Data masuk, gambar peta keluar. Satu URL merender peta choropleth, kategori, atau pin untuk negara, negara bagian, county, atau area ZIP mana pun sebagai PNG. Tanpa akun, tanpa kunci, tanpa pustaka peta di stack Anda.

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

Itulah seluruh permintaannya. Parameter spec adalah JSON yang di-URL-encode, dan responsnya adalah gambar itu sendiri.

Dirender langsung oleh URL di sebelah kiri, di-cache selama 24 jam.

Bisa dipasang di mana saja

URL mengembalikan gambar, jadi bisa dipakai di tag <img>, README, halaman Notion, atau sel Google Sheets.

GET atau POST

GET menerima semua fitur tetapi membatasi spec hingga 6KB, dan selalu merender PNG tanpa kunci hingga 1600px. Kirim JSON yang sama ke POST /v1/renders untuk payload yang lebih besar, kunci untuk kanvas yang lebih besar, atau kunci Pro untuk SVG.

Bisa diedit setelahnya

Setiap gambar membawa header Link yang membuka render di Ultimaps Studio sebagai peta sungguhan. Render tanpa kunci terbuka untuk siapa saja yang memiliki tautan. Render dengan kunci hanya terbuka untuk seseorang yang masuk ke workspace kunci tersebut.

Cookbook

Enam permintaan lengkap. Semuanya divalidasi terhadap skema permintaan langsung di CI, jadi Anda bisa menyalinnya apa adanya, mengganti mapId dan nilainya, lalu langsung jalan. Setiap gambar adalah respons yang dikembalikan oleh permintaan di sebelahnya, termasuk watermark, pada tier gratis tanpa kunci.

Sorot beberapa wilayah

Permintaan berguna yang paling sederhana. Anda menyebutkan wilayah dan memberi masing-masing satu warna. Sisanya mengikuti default peta.

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

Peta Amerika Serikat berjudul "Where we operate", dengan California biru, Texas oranye, dan New York hijau, setiap negara bagian lain memakai default tema dan diberi label singkatannya

• Kunci wilayah fleksibel. "US-CA", "California", dan "CA" semuanya mencapai wilayah yang sama.
• Warna adalah string hex. Wilayah yang tidak Anda sertakan tetap memakai default tema.
• "style.labels.show" mencetak setiap nama wilayah. Untuk membiarkan sebagian wilayah tanpa label, daftarkan kuncinya di "style.labels.hide".

Buka render ini di tab baru

Choropleth dari angka

Berikan nilai mentah ke API dan API memilih kelas, warna, dan legenda. Inilah permintaan yang paling banyak diinginkan orang.

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

Peta choropleth populasi negara bagian AS pada 2025, diwarnai dalam lima kelas kuantil biru dengan label batas di legenda dan setiap nilai dicetak dalam satuan juta di negara bagiannya

• Biarkan "type", "classes", dan "method" kosong dan API mendeteksinya dari data Anda.
• "palette" menerima salah satu dari 26 palet bawaan. "noDataColor" mewarnai wilayah yang tidak tercakup data Anda, dan "noData" menambahkan baris "No data" untuk wilayah tersebut di legenda.
• "legend.title" memberi nama apa yang diukur oleh warna. Beri judul pada setiap legenda data.
• "format" mengontrol bagaimana angka dicetak di legenda dan di peta, bukan format gambar.
• "style.labels.content" di sini adalah "value". "name_value" mencetak nama negara bagian dengan angkanya di bawahnya.

Buka render ini di tab baru

Pin

Penanda lintang dan bujur. Pin bisa digabungkan dengan semua hal lain, jadi Anda bisa menaruhnya di atas choropleth atau peta biasa.

Output SVG memerlukan kunci Pro. Hapus "format" untuk PNG di tier mana pun.

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

Ditampilkan sebagai PNG — permintaan meminta SVG. Peta tetap sama.

• Setiap pin memiliki warna, sisi label, dan visibilitas labelnya sendiri.
• Pin ditempatkan berdasarkan koordinat. API tidak melakukan geocoding alamat.

SVG memerlukan kunci Pro. Jalur GET tanpa kunci hanya mengembalikan PNG.

Periksa permintaan sebelum merendernya

Dry run mengembalikan JSON alih-alih gambar: kunci mana yang cocok, mana yang tidak, apa yang dikoreksi, dan bagaimana batas kelasnya dihasilkan. Tidak memakan kuota.

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

• Salah ketik "Calfornia" dikembalikan terkoreksi menjadi California. "Atlantis" dikembalikan tidak cocok.
• Gunakan ini saat Anda menyiapkan data, lalu matikan "dryRun".

Buka JSON dry-run yang dikembalikan

Gagal pada kunci yang salah alih-alih menebak

Secara default kunci yang tidak cocok dilewati. Setel "onUnmatched" ke "error" dan API mengembalikan 400 dengan saran per kunci, yang Anda inginkan dalam tugas terjadwal.

{
  "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 adalah dokumen masalah RFC 9457. Bercabanglah pada "code", bukan pada pesannya.

Buka 400 yang dikembalikan

Referensi bidang lengkap, termasuk semua 26 palet, empat metode batas kelas, tema, lapisan tambahan, dan pemformatan angka: referensi API.

Peta yang bisa Anda render

189 peta, dari peta dunia dan benua hingga county AS dan area kode ZIP. mapId adalah slug peta di situs ini, dan tidak pernah berubah setelah diterbitkan.

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

Kunci dan batasan

Kunci menaikkan batas laju dan ukuran kanvas. Kunci Pro menghapus watermark dan membuka SVG. Buat satu di Studio di bawah Workspace, lalu API. Kunci hanya ditampilkan sekali.

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

Tier	Auth	Format	Atribusi	Kanvas	Batas laju	Bulanan
Tanpa kunci	tidak ada	PNG	watermark penuh	≤ 1600 px, skala 1	30/jam per IP, burst 5/menit	tanpa batas bulanan
Kunci gratis	Bearer um_live_…	PNG	watermark penuh	≤ 1600 px, skala ≤ 2	10/menit, 50/hari	500 render
Kunci Pro	Bearer um_live_…	PNG, SVG	tidak ada	≤ 4000 px, skala ≤ 4	30/menit, 1.000/hari	5.000 render

Kuota bulanan adalah status penagihan dan mengembalikan 402, tidak pernah bisa diulang. Batas laju dan konkurensi mengembalikan 429 dengan Retry-After. Dry run tidak pernah memakan kuota. Periksa GET /v1/usage untuk melihat posisi Anda.

Dari ChatGPT, Claude, atau klien MCP mana pun

Gunakan API ini dari ChatGPT, Claude, Cursor, atau klien MCP mana pun dan dapatkan peta kembali di dalam chat. Tambahkan https://api.ultimaps.com/mcp berdasarkan URL, atau jalankan paket @ultimaps/mcp di komputer Anda. Keduanya tidak memerlukan akun.

Set up the Ultimaps MCP server

Tidak ada di v1

v1 merender gambar. v1 tidak melakukan hal-hal berikut:

• Menerbitkan peta interaktif atau yang bisa disematkan
• Output PDF
• Geocoding alamat ke koordinat
• Membaca kembali geometri di balik sebuah peta

Jika Anda memerlukan salah satunya, beri tahu kami yang mana dan kami akan memberi tahu Anda saat tersedia. Apa yang orang minta di sini adalah apa yang kami bangun selanjutnya.

Referensi

Referensi API

Setiap endpoint dan bidang, langsung terhadap API yang berjalan.

Kode kesalahan

Setiap kode, status HTTP-nya, dan apakah harus diulang.

openapi.json

Kontrak OpenAPI 3.1. Hasilkan klien darinya.

llms-full.txt

Seluruh API sebagai satu file teks biasa untuk agen coding.

Server MCP

Tambahkan https://api.ultimaps.com/mcp berdasarkan URL, atau jalankan @ultimaps/mcp secara lokal. Tidak perlu akun.

Pertanyaan yang Sering Diajukan

Apakah ada API choropleth?

Ya, itulah hal utama yang dilakukan API ini. Kirim sekumpulan kunci wilayah dan angka dan Anda mendapatkan kembali peta yang terklasifikasi, berwarna, dan berlegenda sebagai PNG. API memilih metode batas kelas, jumlah kelas, dan palet dari data Anda kecuali Anda menetapkannya sendiri.

Bagaimana cara membuat gambar peta dari URL?

Letakkan JSON permintaan Anda di parameter kueri spec dari GET /v1/renders dan responsnya adalah PNG itu sendiri. URL itu berfungsi di tag img, gambar markdown, blok gambar Notion, atau formula IMAGE() Google Sheets, tanpa kunci dan tanpa akun.

Bisakah saya menggunakan API gambar peta tanpa kunci API?

Ya. Tier tanpa kunci merender PNG hingga 1600 kali 1600 piksel pada 30 render per jam per IP, dengan watermark Ultimaps. Kunci menaikkan batas, dan kunci Pro menghapus watermark serta menambahkan SVG.

Apakah ini API peta county? Bisakah saya mendapatkan batas county darinya?

API ini merender peta county sebagai gambar, termasuk semua 3.143 county AS, tetapi tidak menyajikan geometri batas. Jika Anda memerlukan GeoJSON atau shapefile untuk diproses sendiri, gunakan Census TIGER atau Natural Earth. API ini mengembalikan gambar.

Apakah API ini melakukan geocoding alamat?

Tidak. Pin ditempatkan berdasarkan lintang dan bujur, dan warna wilayah dicocokkan berdasarkan kunci atau nama wilayah. Geocoding adalah fitur Studio, bukan fitur API.

Apakah ada server MCP?

Ya. Tambahkan https://api.ultimaps.com/mcp berdasarkan URL di ChatGPT, Claude, atau klien MCP mana pun, atau jalankan paket @ultimaps/mcp secara lokal, dan asisten Anda mendapatkan render_map, list_maps, dan get_map_regions tanpa perlu akun. Langkah penyiapan untuk setiap klien ada di ultimaps.com/mcp/.

Bisakah saya mendapatkan SVG alih-alih PNG?

Ya, dengan kunci Pro. Setel output.format ke svg. Kunci tanpa kunci dan gratis mengembalikan PNG.

Apa yang terjadi jika nama wilayah saya tidak cocok?

Kunci dicocokkan tanpa membedakan huruf besar-kecil terhadap kode wilayah, judul, alias umum, dan judul yang dinormalisasi, sehingga US-CA, California, dan CA semuanya mencapai wilayah yang sama, dan salah ketik yang tidak ambigu dikoreksi serta dilaporkan. Secara default kunci yang tidak cocok dilewati dan dilaporkan di header respons. Setel onUnmatched ke error dan permintaan gagal dengan saran per kunci.

Bagaimana cara menaruh peta di README GitHub?

Gunakan URL GET tanpa kunci sebagai gambar markdown. GitHub memproksinya melalui Camo, dan karena API mengirim header cache 24 jam, gambar diperbarui setiap hari alih-alih membeku.

Bisakah saya merender peta di sisi server?

Ya. Setiap render terjadi di server kami, jadi tidak ada browser, tidak ada Chrome headless, dan tidak ada pustaka peta di stack Anda. Satu panggilan HTTP mengembalikan gambar yang sudah jadi.