Ultimaps MCP

Harita Görüntü API'si

Veri girer, harita görüntüsü çıkar. Tek bir URL, herhangi bir ülkenin, eyaletin, ilçenin veya ZIP bölgesinin koroplet, kategori veya pin haritasını PNG olarak oluşturur. Hesap yok, anahtar yok, yığınınızda harita kütüphanesi yok.

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

İstek tamamen bundan ibaret. spec parametresi URL kodlu JSON'dur ve yanıt görüntünün kendisidir.

Soldaki URL tarafından canlı olarak oluşturulur, 24 saat önbellekte tutulur.

Her yere eklenir

URL görüntüyü döndürür, bu yüzden bir <img> etiketinde, README'de, Notion sayfasında veya Google Sheets hücresinde çalışır.

GET veya POST

GET tüm özellikleri alır ancak spesifikasyonu 6KB ile sınırlar ve her zaman anahtarsız PNG'yi 1600px'e kadar oluşturur. Aynı JSON'u POST /v1/renders adresine gönderin; daha büyük yük, daha büyük tuval için anahtar veya SVG için Pro anahtarı alırsınız.

Sonradan düzenlenebilir

Her görüntü, oluşturmayı Ultimaps Studio'da gerçek bir harita olarak açan bir Link başlığı taşır. Anahtarsız oluşturmalar, bağlantıya sahip herkes için açılır. Anahtarlı bir oluşturma, yalnızca o anahtarın çalışma alanına giriş yapmış biri için açılır.

Yemek Kitabı

Altı eksiksiz istek. Her biri CI'da canlı istek şemasına karşı doğrulanır, böylece oldukları gibi kopyalayabilir, mapId ve değerleri değiştirebilir ve devam edebilirsiniz. Her görüntü, yanındaki isteğin döndürdüğü yanıttır, filigran dahil, ücretsiz anahtarsız katmanda.

Birkaç bölgeyi vurgulayın

En basit kullanışlı istek. Bölgeleri adlandırır ve her birine bir renk verirsiniz. Diğer her şey harita varsayılanını alır.

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

"Faaliyet gösterdiğimiz yerler" başlıklı Amerika Birleşik Devletleri haritası, Kaliforniya mavi, Teksas turuncu ve New York yeşil, diğer tüm eyaletler tema varsayılanında ve kısaltmalarıyla etiketlenmiş

• Bölge anahtarları esnektir. "US-CA", "California" ve "CA" aynı bölgeye ulaşır.
• Renkler hex dizeleridir. Dışarıda bıraktığınız bölgeler tema varsayılanını korur.
• "style.labels.show" her bölge adını yazdırır. Yalnızca renklendirdiğiniz bölgeleri etiketlemenin bir yolu yoktur.

Bu oluşturmayı yeni sekmede aç

Sayılardan koroplet

API'ye ham değerler verin, sınıfları, renkleri ve göstergeyi seçsin. Çoğu insanın istediği istek budur.

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

2025 ABD eyalet nüfusunun koroplet haritası, beş mavi nicelik sınıfı boyunca gölgelendirilmiş, kırılma etiketleri göstergede ve her değer eyaletinde milyonlar olarak yazılmış

• "type", "classes" ve "method" alanlarını boş bırakın, API bunları verilerinizden algılar.
• "palette" yerleşik 26 paletten herhangi birini alır. "noDataColor", verilerinizin kapsamadığı bölgeleri boyar.
• "format" göstergedeki kırılma etiketlerini kontrol eder, görüntü formatını değil.

Bu oluşturmayı yeni sekmede aç

Pinler

Enlem ve boylam işaretçileri. Pinler diğer her şeyle birleşir, böylece onları bir koroplet veya düz bir harita üzerine bırakabilirsiniz.

SVG çıktısı Pro anahtarı gerektirir. Herhangi bir katmanda PNG için "format" alanını bırakın.

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

PNG olarak gösterilir — istek SVG ister. Her iki durumda da aynı harita.

• Her pin kendi rengini, etiket tarafını ve etiket görünürlüğünü alır.
• Pinler koordinatlarla yerleştirilir. API adresleri coğrafi kodlamaz.

SVG bir Pro anahtarı gerektirir. Anahtarsız GET yolu yalnızca PNG döndürür.

Oluşturmadan önce bir isteği kontrol edin

Kuru çalıştırma görüntü yerine JSON döndürür: hangi anahtarlarınız eşleşti, hangileri eşleşmedi, ne düzeltildi ve kırılmalar ne olarak çıktı. Kota harcamaz.

{
  "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" yazım hatası Kaliforniya olarak düzeltilmiş olarak geri gelir. "Atlantis" eşleşmemiş olarak geri gelir.
• Verilerinizi bağlarken bunu kullanın, ardından "dryRun" alanını kapatın.

Bunun döndürdüğü kuru çalıştırma JSON'unu aç

Tahmin etmek yerine hatalı anahtarlarda başarısız olun

Varsayılan olarak eşleşmeyen anahtarlar atlanır. "onUnmatched" alanını "error" olarak ayarlayın ve API, anahtar başına önerilerle birlikte bir 400 döndürür; bu, zamanlanmış bir işte istediğiniz şeydir.

{
  "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, bir RFC 9457 sorun belgesidir. Mesaja değil, "code" alanına göre dallanın.

Bunun döndürdüğü 400'ü aç

Tüm 26 palet, dört kırılma yöntemi, temalar, ekstra katmanlar ve sayı biçimlendirme dahil tam alan referansı: API referansı.

Oluşturabileceğiniz haritalar

Dünya ve kıta haritalarından ABD ilçeleri ve ZIP kodu bölgelerine kadar 187 harita. mapId, haritanın bu sitedeki kısa adıdır ve yayınlandıktan sonra asla değişmez.

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

Anahtarlar ve limitler

Bir anahtar, hız limitlerini ve tuval boyutunu yükseltir. Bir Pro anahtarı filigranı kaldırır ve SVG'nin kilidini açar. Studio'da Çalışma Alanı altında bir tane oluşturun, ardından API. Anahtarlar yalnızca bir kez gösterilir.

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

Katman	Kimlik Doğrulama	Formatlar	Atıf	Tuval	Hız limiti	Aylık
Anahtarsız	yok	PNG	tam filigran	≤ 1600 px, ölçek 1	IP başına saatte 30, patlama 5/dk	aylık sınır yok
Ücretsiz anahtar	Bearer um_live_…	PNG	tam filigran	≤ 1600 px, ölçek ≤ 2	10/dk, 50/gün	500 oluşturma
Pro anahtar	Bearer um_live_…	PNG, SVG	yok	≤ 4000 px, ölçek ≤ 4	30/dk, 1.000/gün	5.000 oluşturma

Aylık kota bir faturalandırma durumudur ve 402 döndürür, asla yeniden denenebilir değildir. Hız ve eşzamanlılık limitleri Retry-After ile 429 döndürür. Kuru çalıştırmalar asla kota tüketmez. Nerede olduğunuzu görmek için GET /v1/usage kontrol edin.

Claude, Codex veya herhangi bir MCP istemcisinden

Sohbette bir harita isteyin ve görüntü konuşmaya geri gelir. @ultimaps/mcp, bu API'nin stdio üzerinden MCP araçları olarak, hesap olmadan sunumudur: render_map, list_maps ve get_map_regions.

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

Bir yapılandırma dosyası okuyan istemciler aynı iki değeri alır. Bu claude_desktop_config.json'dir.

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

Anahtarsız katman için ULTIMAPS_API_KEY alanını boş bırakın, yukarıdaki tabloyla aynı limitler, veya planınızın kotası ve çıktısı için doldurun.

v1'de yok

v1 görüntüler oluşturur. Şunların hiçbirini yapmaz:

• Etkileşimli veya gömülebilir haritalar yayınlama
• PDF çıktısı
• Adresleri koordinatlara coğrafi kodlama
• Bir haritanın arkasındaki geometriyi geri okuma

Bunlardan birine ihtiyacınız varsa, hangisi olduğunu söyleyin, ne zaman var olacağını size bildirelim. İnsanların burada istedikleri, sırada neyi inşa ettiğimizdir.

Referans

API referansı

Çalışan API'ye karşı canlı her uç nokta ve alan.

Hata kodları

Her kod, HTTP durumu ve yeniden denenip denenmeyeceği.

openapi.json

OpenAPI 3.1 sözleşmesi. Ondan bir istemci oluşturun.

llms-full.txt

Kodlama aracıları için tüm API tek bir düz metin dosyası olarak.

@ultimaps/mcp

MCP sunucusu. Üç araç, stdio, hesap gerekmez.

Sıkça Sorulan Sorular

Koroplet API'si var mı?

Evet, bu API'nin ana işi budur. Bir dizi bölge anahtarı ve sayı gönderin, sınıflandırılmış, renklendirilmiş, göstergeli bir haritayı PNG olarak geri alırsınız. API, kırılma yöntemini, sınıf sayısını ve paleti verilerinizden seçer, siz kendiniz ayarlamadıkça.

Bir URL'den harita görüntüsü nasıl oluştururum?

İstek JSON'unuzu GET /v1/renders'ın spec sorgu parametresine koyun ve yanıt PNG'nin kendisidir. Bu URL, anahtar ve hesap olmadan bir img etiketinde, markdown görüntüsünde, Notion görüntü bloğunda veya Google Sheets IMAGE() formülünde çalışır.

Harita görüntü API'sini API anahtarı olmadan kullanabilir miyim?

Evet. Anahtarsız katman, IP başına saatte 30 oluşturma ile 1600 x 1600 piksele kadar PNG oluşturur, Ultimaps filigranı ile. Bir anahtar limitleri yükseltir ve bir Pro anahtarı filigranı kaldırır ve SVG ekler.

Bu bir ilçe haritası API'si mi? Ondan ilçe sınırları alabilir miyim?

İlçe haritalarını görüntü olarak oluşturur, tüm 3.143 ABD ilçesi dahil, ancak sınır geometrisi sunmaz. Kendiniz işlemek için GeoJSON veya shapefile'a ihtiyacınız varsa, bunun yerine Census TIGER veya Natural Earth kullanın. Bu API resimler döndürür.

Adresleri coğrafi kodlar mı?

Hayır. Pinler enlem ve boylamla yerleştirilir ve bölge renkleri bölge anahtarı veya adıyla eşleştirilir. Coğrafi kodlama bir Studio özelliğidir, API özelliği değil.

Bir MCP sunucusu var mı?

Evet. @ultimaps/mcp'yi Claude Code, Codex, Claude Desktop, Cursor, VS Code veya başka herhangi bir MCP istemcisine kurun ve stdio üzerinden render_map, list_maps ve get_map_regions sunar. Node.js 20 veya daha yenisinde çalışır, hesap gerektirmez ve bir tane ayarladığınızda ULTIMAPS_API_KEY okur.

PNG yerine SVG alabilir miyim?

Evet, Pro anahtarıyla. output.format alanını svg olarak ayarlayın. Anahtarsız ve ücretsiz anahtarlar PNG döndürür.

Bölge adlarım eşleşmezse ne olur?

Anahtarlar, bölge kodlarına, başlıklara, yaygın takma adlara ve normalleştirilmiş başlıklara karşı büyük/küçük harf duyarsız eşleştirilir, bu yüzden US-CA, California ve CA aynı bölgeye ulaşır ve belirsiz yazım hataları düzeltilir ve raporlanır. Varsayılan olarak eşleşmeyen anahtarlar atlanır ve bir yanıt başlığında raporlanır. onUnmatched alanını error olarak ayarlayın ve istek, anahtar başına önerilerle başarısız olur.

Bir GitHub README'sine haritayı nasıl koyarım?

Anahtarsız GET URL'sini bir markdown görüntüsü olarak kullanın. GitHub onu Camo aracılığıyla proxy'ler ve API 24 saatlik bir önbellek başlığı gönderdiği için görüntü donmak yerine günlük yenilenir.

Haritayı sunucu tarafında oluşturabilir miyim?

Evet. Her oluşturma bizim sunucularımızda gerçekleşir, bu yüzden yığınınızda tarayıcı, başsız Chrome veya harita kütüphanesi yoktur. Tek bir HTTP çağrısı bitmiş görüntüyü döndürür.