Ultimaps MCP

API Gambar Peta

Data masuk, gambar peta keluar. Satu URL merender peta choropleth, kategori, atau pin dari negara, negara bagian, county, atau area kode POS mana pun sebagai PNG. Tanpa akun, tanpa kunci, tanpa pustaka peta di tumpukan 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 permintaan. Parameter spec adalah JSON yang di-encode URL, 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, sehingga berfungsi dalam tag <img>, README, halaman Notion, atau sel Google Sheets.

GET atau POST

GET menerima semua fitur tetapi membatasi spesifikasi pada 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.

Dapat diedit setelahnya

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

Buku Resep

Enam permintaan lengkap. Setiap permintaan divalidasi terhadap skema permintaan langsung di CI, sehingga Anda dapat menyalinnya apa adanya, ganti mapId dan nilainya, lalu jalankan. Setiap gambar adalah respons dari permintaan di sebelahnya, termasuk watermark, pada tingkat tanpa kunci gratis.

Sorot beberapa wilayah

Permintaan berguna yang paling sederhana. Anda menyebutkan wilayah dan memberi warna pada masing-masing. Semua yang lain menggunakan 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 menggunakan default tema dan diberi label dengan singkatannya

• Kunci wilayah fleksibel. "US-CA", "California", dan "CA" semuanya menjangkau wilayah yang sama.
• Warna adalah string hex. Wilayah yang Anda lewati tetap menggunakan default tema.
• "style.labels.show" mencetak setiap nama wilayah. Tidak ada cara untuk memberi label hanya pada wilayah yang Anda warnai.

Buka render ini di tab baru

Choropleth dari angka

Berikan nilai mentah ke API dan API akan memilih kelas, warna, dan legenda. Ini adalah 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",
    "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

Peta choropleth populasi negara bagian AS pada 2025, diarsir dalam lima kelas kuantil biru dengan label pemisah di legenda dan setiap nilai dicetak dalam jutaan di negara bagiannya

• Hapus "type", "classes", dan "method" dan API akan mendeteksinya dari data Anda.
• "palette" menerima salah satu dari 26 palet bawaan. "noDataColor" mewarnai wilayah yang tidak tercakup oleh data Anda.
• "format" mengontrol label pemisah di legenda, bukan format gambar.

Buka render ini di tab baru

Pin

Penanda lintang dan bujur. Pin dapat digabungkan dengan semua yang lain, sehingga Anda dapat meletakkannya di choropleth atau di peta polos.

Output SVG memerlukan kunci Pro. Hapus "format" untuk PNG di tingkat 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 yang sama apa pun caranya.

• Setiap pin memiliki warna, sisi label, dan visibilitas label 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 hasil pemisahannya. Ini tidak menghabiskan 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
  }'

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

Buka JSON dry-run yang dikembalikan ini

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 pekerjaan 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. Bercabang pada "code", bukan pada pesan.

Buka 400 yang dikembalikan ini

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

Peta yang dapat Anda render

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

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

Kunci dan batasan

Kunci menaikkan batas kecepatan 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",
      "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

Tingkat	Auth	Format	Atribusi	Kanvas	Batas kecepatan	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 dapat dicoba ulang. Batas kecepatan dan konkurensi mengembalikan 429 dengan Retry-After. Dry run tidak pernah menghabiskan kuota. Periksa GET /v1/usage untuk mengetahui posisi Anda.

Dari Claude, Codex, atau klien MCP mana pun

Minta peta di obrolan dan gambar akan kembali dalam percakapan. @ultimaps/mcp adalah API ini sebagai alat MCP melalui stdio, tanpa akun: render_map, list_maps, dan get_map_regions.

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

Klien yang membaca file konfigurasi mengambil dua nilai yang sama. Ini adalah claude_desktop_config.json.

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

Biarkan ULTIMAPS_API_KEY kosong untuk tingkat tanpa kunci, batas yang sama dengan tabel di atas, atau isi untuk kuota dan output paket Anda.

Tidak ada di v1

v1 merender gambar. Ini tidak melakukan semua ini:

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

Jika Anda memerlukan salah satu dari ini, beri tahu kami yang mana dan kami akan memberi tahu Anda kapan tersedia. Apa yang orang minta di sini adalah yang kami bangun berikutnya.

Referensi

Referensi API

Setiap endpoint dan bidang, langsung terhadap API yang berjalan.

Kode kesalahan

Setiap kode, status HTTP-nya, dan apakah akan mencoba ulang.

openapi.json

Kontrak OpenAPI 3.1. Buat klien darinya.

llms-full.txt

Seluruh API sebagai satu file teks biasa untuk agen pengkodean.

@ultimaps/mcp

Server MCP. Tiga alat, stdio, tanpa akun.

Pertanyaan yang Sering Diajukan

Apakah ada API choropleth?

Ya, itu adalah hal utama yang dilakukan API ini. Kirim satu set kunci wilayah dan angka dan Anda mendapatkan peta terklasifikasi, berwarna, berlegenda sebagai PNG. API memilih metode pemisahan, jumlah kelas, dan palet dari data Anda kecuali Anda mengaturnya 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 rumus IMAGE() Google Sheets, tanpa kunci dan tanpa akun.

Bisakah saya menggunakan API gambar peta tanpa kunci API?

Ya. Tingkat 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 dan menambahkan SVG.

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

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 sebagai gantinya. API ini mengembalikan gambar.

Apakah ini melakukan geocoding alamat?

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

Apakah ada server MCP?

Ya. Instal @ultimaps/mcp di Claude Code, Codex, Claude Desktop, Cursor, VS Code, atau klien MCP lainnya dan ini mengekspos render_map, list_maps, dan get_map_regions melalui stdio. Ini berjalan di Node.js 20 atau lebih baru, tidak memerlukan akun, dan membaca ULTIMAPS_API_KEY saat Anda mengaturnya.

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 menjangkau wilayah yang sama, dan kesalahan ketik yang tidak ambigu dikoreksi dan dilaporkan. Secara default, kunci yang tidak cocok dilewati dan dilaporkan di header respons. Setel onUnmatched ke error dan permintaan gagal dengan saran per kunci sebagai gantinya.

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 disegarkan setiap hari alih-alih membeku.

Bisakah saya merender peta di sisi server?

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