Ultimaps MCP

offiziell

Verwandeln Sie Daten in Kartenbilder: Choroplethen-, Kategorie- und Pin-Karten der Welt, Länder, Bundesstaaten, Countys und Postleitzahlen.

Auf ultimaps.com ansehen

Was kann man mit Ultimaps MCP machen?

Eine Karte aus Daten rendern — Bitten Sie Ihren Assistenten, Regionswerte in ein farbiges Choroplethen-Kartenbild mit Legende und Titel umzuwandeln.
Bestimmte Regionen hervorheben — Fordern Sie eine Karte an, in der benannte Bundesstaaten, Landkreise oder Länder mit ausgewählten Hex-Farben gefüllt sind.
Pins anhand von Koordinaten platzieren — Bitten Sie um beschriftete Pins an gegebenen Breiten- und Längengraden, optional kombiniert mit einem Choroplethen.
Verfügbare Karten auflisten — Lassen Sie Ihren Assistenten nachschlagen, welche Karten-IDs existieren, wie etwa united-states oder europe.
Regionsschlüssel vor dem Rendern prüfen — Führen Sie einen Probelauf durch, um zu sehen, welche Regionsnamen übereinstimmten, welche korrigiert wurden und welche fehlgeschlagen sind.
Die Regionen einer Karte nachschlagen — Fragen Sie, welche Regionen eine bestimmte Karte enthält, damit Sie gültige Schlüssel für ein Rendering erstellen können.

Dokumentation

Map-Image-API

Daten rein, Kartenbild raus. Eine URL rendert eine Choropleth-, Kategorie- oder Pin-Karte eines beliebigen Landes, Bundesstaats, Countys oder ZIP-Gebiets als PNG. Kein Konto, kein Key, keine Kartenbibliothek in deinem Stack.

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

Das ist die gesamte Anfrage. Der Parameter spec ist URL-kodiertes JSON, und die Antwort ist das Bild selbst.

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

Live gerendert durch die URL links, 24 Stunden lang gecacht.

Passt überall hinein

Die URL liefert das Bild zurück, also funktioniert sie in einem <img>-Tag, einer README, einer Notion-Seite oder einer Google-Sheets-Zelle.

GET oder POST

GET nimmt jedes Feature, begrenzt die Spec aber auf 6 KB und rendert immer ein keyloses PNG bis 1600 px. Sende dasselbe JSON an POST /v1/renders für eine größere Payload, einen Key für eine größere Leinwand oder einen Pro-Key für SVG.

Danach bearbeitbar

Jedes Bild trägt einen Link-Header, der das Render in Ultimaps Studio als echte Karte öffnet. Keylose Renders öffnen sich für jeden mit dem Link. Ein Render mit Key öffnet sich nur für jemanden, der im Workspace dieses Keys angemeldet ist.

Cookbook

Sechs vollständige Anfragen. Jede wird in CI gegen das Live-Anfrageschema validiert, du kannst sie also unverändert kopieren, den mapId und die Werte austauschen und loslegen. Jedes Bild ist die Antwort, die die danebenstehende Anfrage zurückgegeben hat, Wasserzeichen inklusive, im kostenlosen keylosen Tarif.

Ein paar Regionen hervorheben

Die einfachste nützliche Anfrage. Du benennst Regionen und gibst jeder eine Farbe. Alles andere übernimmt den Kartenstandard.

{
  "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 labeled with its abbreviation

Karte der Vereinigten Staaten mit dem Titel „Where we operate“, mit Kalifornien in Blau, Texas in Orange und New York in Grün, alle anderen Bundesstaaten im Theme-Standard und mit ihrer Abkürzung beschriftet

Regionsschlüssel sind flexibel. „US-CA“, „California“ und „CA“ erreichen alle dieselbe Region.
Farben sind Hex-Strings. Regionen, die du weglässt, behalten den Theme-Standard.
„style.labels.show“ druckt jeden Regionsnamen. Um einige Regionen unbeschriftet zu lassen, liste ihre Schlüssel in „style.labels.hide“ auf.

Dieses Render in einem neuen Tab öffnen

Choropleth aus Zahlen

Gib der API Rohwerte, und sie wählt die Klassen, die Farben und die Legende. Das ist die Anfrage, die die meisten wollen.

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

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

Choropleth-Karte der US-Bundesstaatsbevölkerung 2025, schattiert über fünf blaue Quantil-Klassen mit den Klassengrenzen-Beschriftungen in einer Legende und jedem Wert in Millionen auf seinem Bundesstaat

Lass „type“, „classes“ und „method“ weg, und die API erkennt sie aus deinen Daten.
„palette“ akzeptiert jede der 26 eingebauten Paletten. „noDataColor“ färbt Regionen, die deine Daten nicht abdecken, und „noData“ fügt ihnen eine Zeile „No data“ zur Legende hinzu.
„legend.title“ benennt, was die Farben messen. Gib jeder Datenlegende einen Titel.
„format“ steuert, wie die Zahlen in der Legende und auf der Karte gedruckt werden, nicht das Bildformat.
„style.labels.content“ ist hier „value“. „name_value“ druckt den Bundesstaatsnamen mit seiner Zahl darunter.

Dieses Render in einem neuen Tab öffnen

Pins

Breiten- und Längengrad-Marker. Pins lassen sich mit allem anderen kombinieren, du kannst sie also auf einen Choropleth oder auf eine einfache Karte setzen.

SVG-Ausgabe erfordert einen Pro-Key. Lass „format“ weg für PNG in jedem Tarif.

{
  "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 labeled pins on Austin, Denver and Seattle, the Austin pin in blue and the other two in the default red

Als PNG gezeigt — die Anfrage verlangt SVG. So oder so dieselbe Karte.

Jeder Pin hat seine eigene Farbe, Beschriftungsseite und Beschriftungssichtbarkeit.
Pins werden über Koordinaten platziert. Die API geocodiert keine Adressen.

SVG braucht einen Pro-Key. Der keylose GET-Pfad liefert nur PNG.

Eine Anfrage prüfen, bevor du sie renderst

Ein Dry Run liefert JSON statt eines Bildes: welche deiner Schlüssel gematcht wurden, welche nicht, was korrigiert wurde und wie die Klassengrenzen ausgefallen sind. Er kostet kein Kontingent.

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

Der Tippfehler „Calfornia“ kommt korrigiert zu California zurück. „Atlantis“ kommt ungematcht zurück.
Nutze das, während du deine Daten anbindest, und schalte dann „dryRun“ aus.

Das JSON öffnen, das dieser Dry Run zurückgibt

Bei schlechten Schlüsseln fehlschlagen statt raten

Standardmäßig werden ungematchte Schlüssel übersprungen. Setze „onUnmatched“ auf „error“, und die API gibt einen 400 mit Vorschlägen pro Schlüssel zurück, was du in einem geplanten Job willst.

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

Der 400 ist ein RFC-9457-Problemdokument. Verzweige auf „code“, nicht auf die Meldung.

Den 400 öffnen, den dieser Aufruf zurückgibt

Vollständige Feldreferenz, inklusive aller 26 Paletten, der vier Break-Methoden, Themes, zusätzlicher Layer und Zahlenformatierung: die API-Referenz.

Karten, die du rendern kannst

189 Karten, von Welt- und Kontinentkarten bis hinunter zu US-Countys und ZIP-Code-Gebieten. Der mapId ist der Slug der Karte auf dieser Seite, und er ändert sich nie, sobald er veröffentlicht ist.

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

Keys und Limits

Ein Key erhöht die Rate-Limits und die Leinwandgröße. Ein Pro-Key entfernt das Wasserzeichen und schaltet SVG frei. Erstelle einen in Studio unter Workspace, dann API. Keys werden nur einmal angezeigt.

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

Tarif	Auth	Formate	Attribution	Leinwand	Rate-Limit	Monatlich
Keylos	keine	PNG	volles Wasserzeichen	≤ 1600 px, Skalierung 1	30/Stunde pro IP, Burst 5/Min.	kein monatliches Limit
Kostenloser Key	Bearer um_live_…	PNG	volles Wasserzeichen	≤ 1600 px, Skalierung ≤ 2	10/Min., 50/Tag	500 Renders
Pro-Key	Bearer um_live_…	PNG, SVG	keins	≤ 4000 px, Skalierung ≤ 4	30/Min., 1.000/Tag	5.000 Renders

Das Monatskontingent ist ein Abrechnungszustand und gibt 402 zurück, niemals wiederholbar. Rate- und Concurrency-Limits geben 429 mit Retry-After zurück. Dry Runs verbrauchen nie Kontingent. Prüfe GET /v1/usage, um zu sehen, wo du stehst.

Aus ChatGPT, Claude oder jedem MCP-Client

Nutze diese API aus ChatGPT, Claude, Cursor oder jedem MCP-Client und bekomme die Karte im Chat zurück. Füge https://api.ultimaps.com/mcp per URL hinzu oder führe das Paket @ultimaps/mcp auf deinem Computer aus. Beides braucht kein Konto.

Den Ultimaps MCP-Server einrichten

Nicht in v1

v1 rendert Bilder. Es macht nichts von all dem:

Interaktive oder einbettbare Karten veröffentlichen
PDF-Ausgabe
Adressen zu Koordinaten geocodieren
Die Geometrie hinter einer Karte zurücklesen

Wenn du eines davon brauchst, sag uns welches, und wir lassen dich wissen, wann es existiert. Was die Leute hier anfragen, ist das, was wir als Nächstes bauen.

Referenz

API-Referenz

Jeder Endpoint und jedes Feld, live gegen die laufende API.

Fehlercodes

Jeder Code, sein HTTP-Status und ob er wiederholt werden sollte.

openapi.json

OpenAPI-3.1-Vertrag. Generiere daraus einen Client.

llms-full.txt

Die ganze API als eine Plain-Text-Datei für Coding-Agenten.

MCP-Server

Füge https://api.ultimaps.com/mcp per URL hinzu oder führe @ultimaps/mcp lokal aus. Kein Konto nötig.

Häufig gestellte Fragen

Gibt es eine Choropleth-API?

Ja, das ist die Hauptsache, die diese API macht. Sende eine Menge von Regionsschlüsseln und Zahlen, und du bekommst eine klassifizierte, farbige Karte mit Legende als PNG zurück. Die API wählt die Break-Methode, die Klassenzahl und die Palette aus deinen Daten, sofern du sie nicht selbst setzt.

Wie generiere ich ein Kartenbild aus einer URL?

Setze dein Anfrage-JSON in den Query-Parameter spec von GET /v1/renders, und die Antwort ist das PNG selbst. Diese URL funktioniert in einem img-Tag, einem Markdown-Bild, einem Notion-Bildblock oder einer IMAGE()-Formel in Google Sheets, ohne Key und ohne Konto.

Kann ich die Map-Image-API ohne API-Key nutzen?

Ja. Der keylose Tarif rendert PNG bis 1600 mal 1600 Pixel bei 30 Renders pro Stunde pro IP, mit einem Ultimaps-Wasserzeichen. Ein Key erhöht die Limits, und ein Pro-Key entfernt das Wasserzeichen und fügt SVG hinzu.

Ist das eine County-Map-API? Kann ich daraus County-Grenzen bekommen?

Sie rendert County-Karten als Bilder, inklusive aller 3.143 US-Countys, aber sie liefert keine Grenzgeometrie. Wenn du GeoJSON oder Shapefiles zum Selbstverarbeiten brauchst, nutze stattdessen Census TIGER oder Natural Earth. Diese API liefert Bilder.

Geocodiert sie Adressen?

Nein. Pins werden über Breiten- und Längengrad platziert, und Regionsfarben werden über Regionsschlüssel oder -namen gematcht. Geocoding ist ein Studio-Feature, kein API-Feature.

Gibt es einen MCP-Server?

Ja. Füge https://api.ultimaps.com/mcp per URL in ChatGPT, Claude oder jedem MCP-Client hinzu oder führe das Paket @ultimaps/mcp lokal aus, und dein Assistent bekommt render_map, list_maps und get_map_regions ohne Konto. Die Einrichtungsschritte für jeden Client findest du unter ultimaps.com/mcp/.

Kann ich SVG statt PNG bekommen?

Ja, mit einem Pro-Key. Setze output.format auf svg. Keylose und kostenlose Keys liefern PNG.

Was passiert, wenn meine Regionsnamen nicht übereinstimmen?

Schlüssel werden ohne Beachtung der Groß-/Kleinschreibung gegen Regionscodes, Titel, gängige Aliase und normalisierte Titel gematcht, sodass US-CA, California und CA alle dieselbe Region erreichen, und eindeutige Tippfehler werden korrigiert und gemeldet. Standardmäßig werden ungematchte Schlüssel übersprungen und in einem Antwort-Header gemeldet. Setze onUnmatched auf error, und die Anfrage schlägt stattdessen mit Vorschlägen pro Schlüssel fehl.

Wie füge ich eine Karte in eine GitHub-README ein?

Nutze die keylose GET-URL als Markdown-Bild. GitHub proxyt sie über Camo, und weil die API einen 24-Stunden-Cache-Header sendet, aktualisiert sich das Bild täglich, statt einzufrieren.

Kann ich eine Karte serverseitig rendern?

Ja. Jedes Render passiert auf unseren Servern, es gibt also keinen Browser, kein Headless-Chrome und keine Kartenbibliothek in deinem Stack. Ein einziger HTTP-Aufruf liefert das fertige Bild.