Ultimaps MCP

Harita Görseli API'si

Veri girer, harita görseli çıkar. Tek bir URL, herhangi bir ülkenin, eyaletin, ilçenin veya posta kodu 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

Tüm istek bu kadar. spec parametresi URL ile kodlanmış JSON'dur ve yanıt görselin kendisidir.

Soldaki URL tarafından canlı olarak oluşturulur, 24 saat önbelleğe alınır.

Her yere yerleşir

URL görseli döndürdüğü için bir <img> etiketinde, bir README'de, bir Notion sayfasında veya bir 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 1600px'e kadar anahtarsız PNG oluşturur. Daha büyük bir yük için aynı JSON'u POST /v1/renders adresine gönderin, daha büyük bir tuval için bir anahtar veya SVG için bir Pro anahtarı kullanın.

Sonradan düzenlenebilir

Her görsel, 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 olduğu gibi kopyalayabilir, mapId ve değerleri değiştirip devam edebilirsiniz. Her görsel, yanındaki isteğin döndürdüğü yanıttır; ücretsiz anahtarsız katmanda filigran dahil.

Birkaç bölgeyi vurgulayın

En basit kullanışlı istek. Bölgeleri adlandırır ve her birine bir renk verirsiniz. Geri kalan 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

"Where we operate" 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 onaltılık dizelerdir. 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. Bazı bölgeleri etiketsiz bırakmak için anahtarlarını "style.labels.hide" içinde listeleyin.

Bu oluşturmayı yeni sekmede aç

Sayılardan koroplet

API'ye ham değerler verin; sınıfları, renkleri ve göstergeyi o seçer. Bu, çoğu kişinin istediği istektir.

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

2025 ABD eyalet nüfusunun koroplet haritası, gösterge içinde kesme etiketleriyle beş mavi kantil sınıfı boyunca gölgelenmiş ve her değer eyaletinin üzerinde milyon cinsinden yazdırılmış

• "type", "classes" ve "method" alanlarını dışarıda bırakın; API bunları verilerinizden algılar.
• "palette" 26 yerleşik paletten herhangi birini alır. "noDataColor" verilerinizin kapsamadığı bölgeleri boyar ve "noData" göstergeye bunlar için bir "No data" satırı ekler.
• "legend.title" renklerin neyi ölçtüğünü adlandırır. Her veri göstergesine bir tane verin.
• "format" sayıların göstergede ve haritada nasıl yazdırılacağını kontrol eder, görsel formatını değil.
• "style.labels.content" burada "value"dur. "name_value" eyalet adını altında numarasıyla yazdırır.

Bu oluşturmayı yeni sekmede aç

Pinler

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

SVG çıktısı bir Pro anahtarı gerektirir. PNG için herhangi bir katmanda "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österiliyor — istek SVG istiyor. 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 olarak 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

Deneme çalıştırması görsel yerine JSON döndürür: anahtarlarınızdan hangilerinin eşleştiği, hangilerinin eşleşmediği, neyin düzeltildiği ve kesmelerin ne çıktığı. Kota tüketmez.

{
  "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ı California olarak düzeltilmiş döner. "Atlantis" eşleşmemiş olarak döner.
• Verilerinizi bağlarken bunu kullanın, sonra "dryRun"u kapatın.

Bu döndürülen deneme çalıştırması JSON'unu aç

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

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

{
  "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 problem belgesidir. Mesaja değil "code"a göre dallanın.

Bu döndürülen 400'ü aç

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

Oluşturabileceğiniz haritalar

Dünya ve kıta haritalarından ABD ilçelerine ve posta kodu bölgelerine kadar 189 harita. mapId bu sitedeki haritanın slug'ıdır ve yayımlandıktan sonra asla değişmez.

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

Anahtarlar ve sınırlar

Bir anahtar hız sınırlarını ve tuval boyutunu yükseltir. Bir Pro anahtarı filigranı kaldırır ve SVG'nin kilidini açar. Studio'da Workspace, ardından API altında bir tane oluşturun. Anahtarlar 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",
      "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

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

Aylık kota bir faturalama durumudur ve 402 döndürür, asla yeniden denenemez. Hız ve eşzamanlılık sınırları Retry-After ile birlikte 429 döndürür. Deneme çalıştırmaları asla kota tüketmez. Nerede olduğunuzu görmek için GET /v1/usage kontrol edin.

ChatGPT, Claude veya herhangi bir MCP istemcisinden

Bu API'yi ChatGPT, Claude, Cursor veya herhangi bir MCP istemcisinden kullanın ve haritayı sohbette geri alın. https://api.ultimaps.com/mcp adresini URL ile ekleyin veya @ultimaps/mcp paketini bilgisayarınızda çalıştırın. İkisi de hesap gerektirmez.

Ultimaps MCP sunucusunu kur

v1'de yok

v1 görseller oluşturur. Şunların hiçbirini yapmaz:

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

Bunlardan birine ihtiyacınız varsa hangisi olduğunu bize söyleyin, var olduğunda size haber verelim. Burada insanların istediği şey, bir sonraki inşa ettiğimiz şeydir.

Referans

API referansı

Çalışan API'ye karşı canlı olarak 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 ajanları için tek bir düz metin dosyası olarak tüm API.

MCP sunucusu

https://api.ultimaps.com/mcp adresini URL ile ekleyin veya @ultimaps/mcp'yi yerel olarak çalıştırın. Hesap gerekmez.

Sıkça Sorulan Sorular

Bir koroplet API'si var mı?

Evet, bu API'nin yaptığı ana şey budur. Bir dizi bölge anahtarı ve sayı gönderin, karşılığında sınıflandırılmış, renklendirilmiş, göstergeli bir haritayı PNG olarak alın. Kendiniz ayarlamadığınız sürece API kesme yöntemini, sınıf sayısını ve paleti verilerinizden seçer.

Bir URL'den nasıl harita görseli oluştururum?

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

Harita görseli API'sini API anahtarı olmadan kullanabilir miyim?

Evet. Anahtarsız katman, IP başına saatte 30 oluşturma hızında, Ultimaps filigranıyla 1600 x 1600 piksele kadar PNG oluşturur. Bir anahtar sınırları 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örsel olarak oluşturur, 3.143 ABD ilçesinin tamamı dahil, ancak sınır geometrisi sunmaz. Kendiniz işlemek için GeoJSON veya shapefile'lara ihtiyacınız varsa bunun yerine Census TIGER veya Natural Earth kullanın. Bu API resimler döndürür.

Adresleri coğrafi olarak 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. https://api.ultimaps.com/mcp adresini ChatGPT, Claude veya herhangi bir MCP istemcisinde URL ile ekleyin veya @ultimaps/mcp paketini yerel olarak çalıştırın; asistanınız hesap gerekmeden render_map, list_maps ve get_map_regions alır. Her istemci için kurulum adımları ultimaps.com/mcp/ adresindedir.

PNG yerine SVG alabilir miyim?

Evet, bir Pro anahtarıyla. output.format değerini 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 olarak eşleştirilir, böylece US-CA, California ve CA aynı bölgeye ulaşır ve belirsiz olmayan yazım hataları düzeltilir ve bildirilir. Varsayılan olarak eşleşmeyen anahtarlar atlanır ve bir yanıt başlığında bildirilir. onUnmatched değerini error olarak ayarlayın ve istek bunun yerine anahtar başına önerilerle başarısız olur.

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

Anahtarsız GET URL'sini bir markdown görseli olarak kullanın. GitHub bunu Camo üzerinden proxy'ler ve API 24 saatlik önbellek başlığı gönderdiği için görsel donmak yerine günlük olarak yenilenir.

Sunucu tarafında bir harita oluşturabilir miyim?

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