Ultimaps MCP

Map Image API

Daten rein, Kartenbild raus. Eine URL rendert eine Choroplethen-, Kategorie- oder Pinnadelkarte jedes Landes, Bundesstaats, Countys oder PLZ-Gebiets als PNG. Kein Konto, kein Schlüssel, keine Kartenbibliothek in Ihrem 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.

Live von der URL links gerendert, 24 Stunden lang zwischengespeichert.

Überall einsetzbar

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

GET oder POST

GET unterstützt jede Funktion, begrenzt die Spezifikation jedoch auf 6 KB und rendert immer schlüsselloses PNG bis 1600 px. Senden Sie dasselbe JSON an POST /v1/renders für eine größere Nutzlast, einen Schlüssel für eine größere Leinwand oder einen Pro-Schlüssel für SVG.

Danach bearbeitbar

Jedes Bild trägt einen Link-Header, der den Render in Ultimaps Studio als echte Karte öffnet. Schlüssellose Renderings öffnen sich für jeden mit dem Link. Ein gerendertes Bild mit Schlüssel öffnet sich nur für jemanden, der im Workspace dieses Schlüssels angemeldet ist.

Kochbuch

Sechs vollständige Anfragen. Jede ist in CI gegen das Live-Anfrageschema validiert, sodass Sie sie direkt kopieren, den mapId und die Werte austauschen und loslegen können. Jedes Bild ist die Antwort, die die danebenstehende Anfrage zurückgegeben hat, inklusive Wasserzeichen, auf der kostenlosen schlüssellosen Stufe.

Einige Regionen hervorheben

Die einfachste nützliche Anfrage. Sie benennen Regionen und geben jeder eine Farbe. Alles andere übernimmt die Kartenstandardwerte.

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

Karte der Vereinigten Staaten mit dem Titel „Where we operate", mit Kalifornien in Blau, Texas in Orange und New York in Grün, jeder andere Bundesstaat im Themenstandard und mit seiner Abkürzung beschriftet

• Regionsschlüssel sind flexibel. „US-CA", „California" und „CA" erreichen alle dieselbe Region.
• Farben sind Hex-Strings. Regionen, die Sie auslassen, behalten die Themenstandardfarbe.
• „style.labels.show" druckt jeden Regionsnamen. Es gibt keine Möglichkeit, nur die von Ihnen eingefärbten Regionen zu beschriften.

Diesen Render in einem neuen Tab öffnen

Choroplethenkarte aus Zahlen

Geben Sie der API Rohwerte, und sie wählt die Klassen, die Farben und die Legende aus. Dies ist die Anfrage, die die meisten Menschen 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",
    "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

Choroplethenkarte der US-Bevölkerung 2025, schattiert über fünf blaue Quantilklassen mit den Bruchbeschriftungen in einer Legende und jedem Wert in Millionen auf seinem Bundesstaat gedruckt

• Lassen Sie „type", „classes" und „method" weg, und die API erkennt sie aus Ihren Daten.
• „palette" akzeptiert jede der 26 integrierten Paletten. „noDataColor" färbt Regionen, die Ihre Daten nicht abdecken.
• „format" steuert die Bruchbeschriftungen in der Legende, nicht das Bildformat.

Diesen Render in einem neuen Tab öffnen

Pinnadeln

Breiten- und Längengradmarkierungen. Pinnadeln kombinieren sich mit allem anderen, sodass Sie sie auf einer Choroplethenkarte oder auf einer einfachen Karte platzieren können.

SVG-Ausgabe erfordert einen Pro-Schlüssel. Lassen Sie „format" für PNG auf jeder Stufe weg.

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

Als PNG angezeigt – die Anfrage fragt nach SVG. Dieselbe Karte in beiden Fällen.

• Jede Pinnadel hat ihre eigene Farbe, Beschriftungsseite und Beschriftungssichtbarkeit.
• Pinnadeln werden nach Koordinaten platziert. Die API geokodiert keine Adressen.

SVG erfordert einen Pro-Schlüssel. Der schlüssellose GET-Pfad gibt nur PNG zurück.

Eine Anfrage prüfen, bevor Sie sie rendern

Der Trockenlauf gibt JSON statt eines Bildes zurück: welche Ihrer Schlüssel übereinstimmten, welche nicht, was korrigiert wurde und wie die Brüche 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" wird korrigiert zu California zurückgegeben. „Atlantis" wird als nicht übereinstimmend zurückgegeben.
• Verwenden Sie dies, während Sie Ihre Daten verdrahten, und schalten Sie dann „dryRun" aus.

Das zurückgegebene Trockenlauf-JSON öffnen

Bei ungültigen Schlüsseln fehlschlagen statt raten

Standardmäßig werden nicht übereinstimmende Schlüssel übersprungen. Setzen Sie „onUnmatched" auf „error", und die API gibt einen 400 mit Schlüsselvorschlägen zurück, was Sie in einem geplanten Job möchten.

{
  "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. Verzweigen Sie auf „code", nicht auf die Nachricht.

Den zurückgegebenen 400 öffnen

Vollständige Feldreferenz, einschließlich aller 26 Paletten, der vier Bruchmethoden, Themen, zusätzlicher Ebenen und Zahlenformatierung: die API-Referenz.

Karten, die Sie rendern können

187 Karten, von Welt- und Kontinentkarten bis hin zu US-Countys und PLZ-Gebieten. Der mapId ist der Slug der Karte auf dieser Website und ändert sich nie, sobald er veröffentlicht ist.

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

Schlüssel und Grenzen

Ein Schlüssel erhöht die Ratengrenzen und die Leinwandgröße. Ein Pro-Schlüssel entfernt das Wasserzeichen und entsperrt SVG. Erstellen Sie einen in Studio unter Workspace, dann API. Schlüssel 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",
      "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

Stufe	Auth	Formate	Attribution	Leinwand	Ratengrenze	Monatlich
Schlüssellos	keine	PNG	volles Wasserzeichen	≤ 1600 px, Skalierung 1	30/Stunde pro IP, Burst 5/Minute	keine monatliche Obergrenze
Kostenloser Schlüssel	Bearer um_live_…	PNG	volles Wasserzeichen	≤ 1600 px, Skalierung ≤ 2	10/Minute, 50/Tag	500 Renderings
Pro-Schlüssel	Bearer um_live_…	PNG, SVG	keine	≤ 4000 px, Skalierung ≤ 4	30/Minute, 1.000/Tag	5.000 Renderings

Das monatliche Kontingent ist ein Abrechnungszustand und gibt 402 zurück, nie wiederholbar. Ratengrenzen und Parallelitätsgrenzen geben 429 mit Retry-After zurück. Trockenläufe verbrauchen nie Kontingent. Prüfen Sie GET /v1/usage für Ihren aktuellen Stand.

Von Claude, Codex oder jedem MCP-Client

Fragen Sie im Chat nach einer Karte, und das Bild kommt im Gespräch zurück. @ultimaps/mcp ist diese API als MCP-Tools über stdio, ohne Konto: render_map, list_maps und get_map_regions.

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

Clients, die eine Konfigurationsdatei lesen, akzeptieren dieselben zwei Werte. Dies ist claude_desktop_config.json.

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

Lassen Sie ULTIMAPS_API_KEY für die schlüssellose Stufe leer, gleiche Grenzen wie in der Tabelle oben, oder füllen Sie es für das Kontingent und die Ausgabe Ihres Plans aus.

Nicht in v1

v1 rendert Bilder. Es macht nichts davon:

• Veröffentlichen interaktiver oder einbettbarer Karten
• PDF-Ausgabe
• Geokodierung von Adressen zu Koordinaten
• Zurücklesen der Geometrie hinter einer Karte

Wenn Sie eines davon benötigen, sagen Sie uns welches, und wir lassen Sie wissen, wann es existiert. Was Menschen hier anfragen, bauen wir als Nächstes.

Referenz

API-Referenz

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

Fehlercodes

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

openapi.json

OpenAPI-3.1-Vertrag. Generieren Sie einen Client daraus.

llms-full.txt

Die gesamte API als eine Klartextdatei für Codierungsagenten.

@ultimaps/mcp

Der MCP-Server. Drei Tools, stdio, kein Konto erforderlich.

Häufig gestellte Fragen

Gibt es eine Choroplethen-API?

Ja, das ist die Hauptfunktion dieser API. Senden Sie eine Reihe von Regionsschlüsseln und Zahlen, und Sie erhalten eine klassifizierte, eingefärbte, mit Legende versehene Karte als PNG. Die API wählt die Bruchmethode, die Klassenanzahl und die Palette aus Ihren Daten, es sei denn, Sie setzen sie selbst.

Wie generiere ich ein Kartenbild aus einer URL?

Setzen Sie Ihr Anfrage-JSON in den Spezifikationsabfrageparameter 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 Google-Sheets-IMAGE()-Formel, ohne Schlüssel und ohne Konto.

Kann ich die Kartenbild-API ohne API-Schlüssel verwenden?

Ja. Die schlüssellose Stufe rendert PNG bis 1600 mal 1600 Pixel bei 30 Renderings pro Stunde pro IP, mit einem Ultimaps-Wasserzeichen. Ein Schlüssel erhöht die Grenzen, und ein Pro-Schlüssel entfernt das Wasserzeichen und fügt SVG hinzu.

Ist dies eine County-Karten-API? Kann ich County-Grenzen daraus erhalten?

Sie rendert County-Karten als Bilder, einschließlich aller 3.143 US-Countys, liefert aber keine Grenzgeometrie. Wenn Sie GeoJSON oder Shapefiles zur eigenen Verarbeitung benötigen, verwenden Sie stattdessen Census TIGER oder Natural Earth. Diese API gibt Bilder zurück.

Geokodiert sie Adressen?

Nein. Pinnadeln werden nach Breiten- und Längengrad platziert, und Regionsfarben werden nach Regionsschlüssel oder -name abgeglichen. Geokodierung ist eine Studio-Funktion, keine API-Funktion.

Gibt es einen MCP-Server?

Ja. Installieren Sie @ultimaps/mcp in Claude Code, Codex, Claude Desktop, Cursor, VS Code oder einem anderen MCP-Client, und er stellt render_map, list_maps und get_map_regions über stdio bereit. Er läuft auf Node.js 20 oder neuer, benötigt kein Konto und liest ULTIMAPS_API_KEY, wenn Sie einen setzen.

Kann ich SVG statt PNG erhalten?

Ja, mit einem Pro-Schlüssel. Setzen Sie output.format auf svg. Schlüssellose und kostenlose Schlüssel geben PNG zurück.

Was passiert, wenn meine Regionsnamen nicht übereinstimmen?

Schlüssel werden ohne Berücksichtigung der Groß-/Kleinschreibung gegen Regionscodes, Titel, allgemeine Aliase und normalisierte Titel abgeglichen, sodass US-CA, California und CA alle dieselbe Region erreichen, und eindeutige Tippfehler werden korrigiert und gemeldet. Standardmäßig werden nicht übereinstimmende Schlüssel übersprungen und in einem Antwortheader gemeldet. Setzen Sie onUnmatched auf error, und die Anfrage schlägt stattdessen mit Schlüsselvorschlägen fehl.

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

Verwenden Sie die schlüssellose GET-URL als Markdown-Bild. GitHub proxied sie durch Camo, und da die API einen 24-Stunden-Cache-Header sendet, aktualisiert sich das Bild täglich statt einzufrieren.

Kann ich eine Karte serverseitig rendern?

Ja. Jedes Rendering passiert auf unseren Servern, sodass es keinen Browser, kein Headless-Chrome und keine Kartenbibliothek in Ihrem Stack gibt. Ein einziger HTTP-Aufruf gibt das fertige Bild zurück.