Ultimaps MCP

आधिकारिक

डेटा को मानचित्र छवियों में बदलें: दुनिया, देशों, राज्यों, काउंटियों और ZIP कोड के कोरोप्लेथ, श्रेणी और पिन मानचित्र।

ultimaps.com पर देखेंइस MCP को आज़माएँप्रायोजित

Ultimaps MCP के साथ आप क्या कर सकते हैं?

Render choropleth maps — किसी संख्यात्मक मान के अनुसार रंगीन नक्शा मांगें, और लीजेंड तथा लेबल के साथ वर्गीकृत PNG प्राप्त करें।
Highlight specific regions — नामित राज्यों, काउंटियों या ZIP क्षेत्रों को कस्टम रंगों में भरा हुआ नक्शा अनुरोध करें, जैसे "हम कहाँ काम करते हैं।"
Add location pins — किसी भी नक्शे पर कस्टम शीर्षक, रंग और लेबल स्थिति के साथ अक्षांश/देशांतर मार्कर लगाएं।
Validate map data — यह जाँचने के लिए ड्राई रन चलाएँ कि कौन से क्षेत्र कुंजियाँ मेल खाती हैं, टाइपो सुधार प्राप्त करें, और रेंडरिंग से पहले ब्रेक मान देखें।
List available maps — पूछें कि 187 नक्शों (देश, राज्य, काउंटी, ZIP क्षेत्र) में से कौन से list_maps के माध्यम से उपलब्ध हैं।
Get region identifiers — अपने रेंडर अनुरोध में उपयोग के लिए नक्शे के क्षेत्रों के सटीक कुंजी या नाम get_map_regions के माध्यम से देखें।

दस्तावेज़

मैप इमेज API

डेटा अंदर, मैप इमेज बाहर। एक URL किसी भी देश, राज्य, काउंटी या ZIP क्षेत्र का कोरोप्लेथ, कैटेगरी या पिन मैप PNG के रूप में रेंडर करता है। कोई खाता नहीं, कोई कुंजी नहीं, आपके स्टैक में कोई मैप लाइब्रेरी नहीं।

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

यही पूरा अनुरोध है। spec पैरामीटर URL-एन्कोडेड JSON है, और प्रतिक्रिया स्वयं इमेज है।

US map rendered by the Ultimaps API, every state labelled, with California, Texas and New York filled in

बाईं ओर URL द्वारा लाइव रेंडर किया गया, 24 घंटे के लिए कैश किया गया।

कहीं भी डालें

URL इमेज लौटाता है, इसलिए यह <img> टैग, README, Notion पेज या Google Sheets सेल में काम करता है।

GET या POST

GET हर सुविधा लेता है लेकिन स्पेक को 6KB पर सीमित करता है, और यह हमेशा 1600px तक बिना कुंजी वाला PNG रेंडर करता है। बड़े पेलोड के लिए वही JSON POST /v1/renders पर भेजें, बड़े कैनवास के लिए कुंजी, या SVG के लिए Pro कुंजी।

बाद में संपादन योग्य

हर इमेज में Link हेडर होता है जो रेंडर को Ultimaps Studio में वास्तविक मैप के रूप में खोलता है। बिना कुंजी वाले रेंडर लिंक वाले किसी भी व्यक्ति के लिए खुलते हैं। कुंजी वाला रेंडर केवल उस व्यक्ति के लिए खुलता है जो उस कुंजी के वर्कस्पेस में साइन इन है।

कुकबुक

छह पूर्ण अनुरोध। हर एक CI में लाइव अनुरोध स्कीमा के विरुद्ध मान्य है, इसलिए आप उन्हें जैसे हैं वैसे कॉपी कर सकते हैं, mapId और मान बदल सकते हैं, और आगे बढ़ सकते हैं। हर इमेज उस अनुरोध की प्रतिक्रिया है जो उसके बगल में लौटी, वॉटरमार्क सहित, मुफ्त बिना कुंजी वाले टियर पर।

कुछ क्षेत्रों को हाइलाइट करें

सबसे सरल उपयोगी अनुरोध। आप क्षेत्रों के नाम बताते हैं और प्रत्येक को एक रंग देते हैं। बाकी सब मैप डिफ़ॉल्ट लेता है।

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

Map of the United States titled "Where we operate", with California blue, Texas orange and New York green, every other state in the theme default and labelled with its abbreviation

"जहाँ हम काम करते हैं" शीर्षक वाले संयुक्त राज्य अमेरिका का मैप, कैलिफोर्निया नीला, टेक्सास नारंगी और न्यूयॉर्क हरा, बाकी हर राज्य थीम डिफ़ॉल्ट में और उसके संक्षिप्त नाम के साथ लेबल किया हुआ

क्षेत्र कुंजियाँ लचीली हैं। "US-CA", "California" और "CA" सभी एक ही क्षेत्र तक पहुँचते हैं।
रंग हेक्स स्ट्रिंग हैं। जिन क्षेत्रों को आप छोड़ते हैं वे थीम डिफ़ॉल्ट रखते हैं।
"style.labels.show" हर क्षेत्र का नाम प्रिंट करता है। केवल उन क्षेत्रों को लेबल करने का कोई तरीका नहीं है जिन्हें आपने रंग दिया है।

इस रेंडर को नए टैब में खोलें

संख्याओं से कोरोप्लेथ

API को कच्चे मान दें और यह क्लास, रंग और लीजेंड चुनता है। यह वह अनुरोध है जो अधिकांश लोग चाहते हैं।

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

Choropleth map of US state population in 2025, shaded across five blue quantile classes with the break labels in a legend and each value printed in millions on its state

2025 में अमेरिकी राज्य जनसंख्या का कोरोप्लेथ मैप, पाँच नीले क्वांटाइल क्लास में छायांकित, लीजेंड में ब्रेक लेबल और प्रत्येक मान अपने राज्य पर मिलियन में मुद्रित

"type", "classes" और "method" छोड़ें और API उन्हें आपके डेटा से पहचान लेता है।
"palette" 26 अंतर्निहित पैलेट में से कोई भी लेता है। "noDataColor" उन क्षेत्रों को रंगता है जिन्हें आपका डेटा कवर नहीं करता।
"format" लीजेंड में ब्रेक लेबल को नियंत्रित करता है, इमेज प्रारूप को नहीं।

इस रेंडर को नए टैब में खोलें

पिन

अक्षांश और देशांतर मार्कर। पिन बाकी सबके साथ संयोजित होते हैं, इसलिए आप उन्हें कोरोप्लेथ या सादे मैप पर डाल सकते हैं।

SVG आउटपुट के लिए Pro कुंजी चाहिए। किसी भी टियर पर PNG के लिए "format" हटाएँ।

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

Map of the United States on a pale theme with labelled pins on Austin, Denver and Seattle, the Austin pin in blue and the other two in the default red

PNG के रूप में दिखाया गया — अनुरोध SVG माँगता है। दोनों तरह से एक ही मैप।

प्रत्येक पिन अपना रंग, लेबल पक्ष और लेबल दृश्यता लेता है।
पिन निर्देशांक द्वारा रखे जाते हैं। API पते जियोकोड नहीं करता।

SVG के लिए Pro कुंजी चाहिए। बिना कुंजी वाला GET पथ केवल PNG लौटाता है।

रेंडर करने से पहले अनुरोध जाँचें

ड्राई रन इमेज के बजाय JSON लौटाता है: आपकी कौन सी कुंजियाँ मेल खाईं, कौन सी नहीं, क्या सुधारा गया और ब्रेक क्या निकले। यह कोई कोटा खर्च नहीं करता।

{
  "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" सुधारकर California लौटता है। "Atlantis" बिना मेल के लौटता है।
अपना डेटा जोड़ते समय इसका उपयोग करें, फिर "dryRun" बंद करें।

यह लौटने वाला ड्राई-रन JSON खोलें

अनुमान लगाने के बजाय खराब कुंजियों पर विफल हों

डिफ़ॉल्ट रूप से बिना मेल वाली कुंजियाँ छोड़ दी जाती हैं। "onUnmatched" को "error" पर सेट करें और API प्रति-कुंजी सुझावों के साथ 400 लौटाता है, जो आप एक निर्धारित कार्य में चाहते हैं।

{
  "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 एक RFC 9457 समस्या दस्तावेज़ है। "code" पर शाखा करें, संदेश पर नहीं।

यह लौटने वाला 400 खोलें

पूर्ण फ़ील्ड संदर्भ, सभी 26 पैलेट, चार ब्रेक विधियाँ, थीम, अतिरिक्त परतें और संख्या स्वरूपण सहित: API संदर्भ।

मैप जो आप रेंडर कर सकते हैं

187 मैप, विश्व और महाद्वीप मैप से लेकर अमेरिकी काउंटी और ZIP कोड क्षेत्रों तक। mapId इस साइट पर मैप का स्लग है, और प्रकाशित होने के बाद यह कभी नहीं बदलता।

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

कुंजियाँ और सीमाएँ

एक कुंजी दर सीमाएँ और कैनवास आकार बढ़ाती है। एक Pro कुंजी वॉटरमार्क हटाती है और SVG अनलॉक करती है। Studio में Workspace, फिर API के अंतर्गत एक बनाएँ। कुंजियाँ केवल एक बार दिखाई जाती हैं।

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

टियर	प्रमाणीकरण	प्रारूप	एट्रिब्यूशन	कैनवास	दर सीमा	मासिक
बिना कुंजी	कोई नहीं	PNG	पूर्ण वॉटरमार्क	≤ 1600 px, स्केल 1	30/घंटा प्रति IP, बर्स्ट 5/मिनट	कोई मासिक सीमा नहीं
मुफ्त कुंजी	Bearer um_live_…	PNG	पूर्ण वॉटरमार्क	≤ 1600 px, स्केल ≤ 2	10/मिनट, 50/दिन	500 रेंडर
Pro कुंजी	Bearer um_live_…	PNG, SVG	कोई नहीं	≤ 4000 px, स्केल ≤ 4	30/मिनट, 1,000/दिन	5,000 रेंडर

मासिक कोटा एक बिलिंग स्थिति है और 402 लौटाता है, कभी पुनः प्रयास योग्य नहीं। दर और समवर्ती सीमाएँ 429 के साथ Retry-After लौटाती हैं। ड्राई रन कभी कोटा उपभोग नहीं करते। आप कहाँ खड़े हैं यह जाँचने के लिए GET /v1/usage देखें।

Claude, Codex या किसी भी MCP क्लाइंट से

चैट में मैप माँगें और इमेज बातचीत में लौट आती है। @ultimaps/mcp इस API को stdio पर MCP टूल के रूप में है, बिना किसी खाते के: render_map, list_maps और get_map_regions।

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

जो क्लाइंट कॉन्फ़िगरेशन फ़ाइल पढ़ते हैं वे वही दो मान लेते हैं। यह claude_desktop_config.json है।

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

बिना कुंजी वाले टियर के लिए ULTIMAPS_API_KEY खाली छोड़ें, ऊपर तालिका के समान सीमाएँ, या अपनी योजना के कोटा और आउटपुट के लिए इसे भरें।

v1 में नहीं

v1 इमेज रेंडर करता है। यह इनमें से कोई नहीं करता:

इंटरैक्टिव या एम्बेडेड मैप प्रकाशित करना
PDF आउटपुट
पतों को निर्देशांक में जियोकोड करना
मैप के पीछे ज्यामिति वापस पढ़ना

यदि आपको इनमें से एक चाहिए, हमें बताएँ कि कौन सा और हम आपको बताएँगे कि यह कब मौजूद होगा। लोग यहाँ जो माँगते हैं वही हम आगे बनाते हैं।

संदर्भ

API संदर्भ

हर एंडपॉइंट और फ़ील्ड, चालू API के विरुद्ध लाइव।

त्रुटि कोड

हर कोड, उसकी HTTP स्थिति, और क्या उसे पुनः प्रयास करना है।

openapi.json

OpenAPI 3.1 अनुबंध। इससे क्लाइंट उत्पन्न करें।

llms-full.txt

पूरा API कोडिंग एजेंटों के लिए एक सादे-पाठ फ़ाइल के रूप में।

@ultimaps/mcp

MCP सर्वर। तीन टूल, stdio, कोई खाता आवश्यक नहीं।

अक्सर पूछे जाने वाले प्रश्न

क्या कोई कोरोप्लेथ API है?

हाँ, यही मुख्य काम है जो यह API करता है। क्षेत्र कुंजियों और संख्याओं का एक सेट पोस्ट करें और आपको वर्गीकृत, रंगीन, लीजेंड वाला मैप PNG के रूप में मिलता है। API आपके डेटा से ब्रेक विधि, क्लास संख्या और पैलेट चुनता है जब तक आप उन्हें स्वयं सेट नहीं करते।

मैं URL से मैप इमेज कैसे उत्पन्न करूँ?

अपना अनुरोध JSON GET /v1/renders के spec क्वेरी पैरामीटर में रखें और प्रतिक्रिया स्वयं PNG है। वह URL img टैग, मार्कडाउन इमेज, Notion इमेज ब्लॉक या Google Sheets IMAGE() सूत्र में काम करता है, बिना कुंजी और बिना खाते के।

क्या मैं API कुंजी के बिना मैप इमेज API का उपयोग कर सकता हूँ?

हाँ। बिना कुंजी वाला टियर 1600 गुणा 1600 पिक्सेल तक PNG रेंडर करता है, 30 रेंडर प्रति घंटे प्रति IP, Ultimaps वॉटरमार्क के साथ। एक कुंजी सीमाएँ बढ़ाती है, और एक Pro कुंजी वॉटरमार्क हटाती है और SVG जोड़ती है।

क्या यह काउंटी मैप API है? क्या मैं इससे काउंटी सीमाएँ प्राप्त कर सकता हूँ?

यह काउंटी मैप को इमेज के रूप में रेंडर करता है, सभी 3,143 अमेरिकी काउंटी सहित, लेकिन यह सीमा ज्यामिति नहीं परोसता। यदि आपको स्वयं प्रक्रिया करने के लिए GeoJSON या shapefiles चाहिए, तो इसके बजाय Census TIGER या Natural Earth का उपयोग करें। यह API चित्र लौटाता है।

क्या यह पते जियोकोड करता है?

नहीं। पिन अक्षांश और देशांतर द्वारा रखे जाते हैं, और क्षेत्र रंग क्षेत्र कुंजी या नाम से मेल खाते हैं। जियोकोडिंग एक Studio सुविधा है, API नहीं।

क्या कोई MCP सर्वर है?

हाँ। Claude Code, Codex, Claude Desktop, Cursor, VS Code या किसी अन्य MCP क्लाइंट में @ultimaps/mcp स्थापित करें और यह stdio पर render_map, list_maps और get_map_regions उजागर करता है। यह Node.js 20 या नए पर चलता है, किसी खाते की आवश्यकता नहीं है, और जब आप सेट करते हैं तो ULTIMAPS_API_KEY पढ़ता है।

क्या मैं PNG के बजाय SVG प्राप्त कर सकता हूँ?

हाँ, Pro कुंजी के साथ। output.format को svg पर सेट करें। बिना कुंजी और मुफ्त कुंजियाँ PNG लौटाती हैं।

यदि मेरे क्षेत्र के नाम मेल नहीं खाते तो क्या होता है?

कुंजियाँ क्षेत्र कोड, शीर्षक, सामान्य उपनाम और सामान्यीकृत शीर्षकों के विरुद्ध केस-असंवेदनशील रूप से मेल खाती हैं, इसलिए US-CA, California और CA सभी एक ही क्षेत्र तक पहुँचते हैं, और स्पष्ट टाइपो सुधारे और रिपोर्ट किए जाते हैं। डिफ़ॉल्ट रूप से बिना मेल वाली कुंजियाँ छोड़ दी जाती हैं और प्रतिक्रिया हेडर में रिपोर्ट की जाती हैं। onUnmatched को error पर सेट करें और अनुरोध इसके बजाय प्रति-कुंजी सुझावों के साथ विफल होता है।

मैं GitHub README में मैप कैसे डालूँ?

बिना कुंजी वाले GET URL को मार्कडाउन इमेज के रूप में उपयोग करें। GitHub इसे Camo के माध्यम से प्रॉक्सी करता है, और क्योंकि API 24 घंटे का कैश हेडर भेजता है, इमेज जमने के बजाय दैनिक रूप से ताज़ा होती है।

क्या मैं सर्वर साइड पर मैप रेंडर कर सकता हूँ?

हाँ। हर रेंडर हमारे सर्वर पर होता है, इसलिए आपके स्टैक में कोई ब्राउज़र, कोई हेडलेस Chrome और कोई मैप लाइब्रेरी नहीं है। एक एकल HTTP कॉल तैयार इमेज लौटाती है।