Ultimaps MCP

API d'images cartographiques

Des données en entrée, une image cartographique en sortie. Une seule URL génère une carte choroplèthe, par catégories ou à repères de n'importe quel pays, État, comté ou zone ZIP au format PNG. Pas de compte, pas de clé, pas de bibliothèque cartographique dans votre pile technique.

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

C'est toute la requête. Le paramètre spec est du JSON encodé dans l'URL, et la réponse est l'image elle-même.

Rendu en direct par l'URL à gauche, mis en cache pendant 24 heures.

S'intègre partout

L'URL renvoie l'image, elle fonctionne donc dans une balise <img>, un README, une page Notion ou une cellule Google Sheets.

GET ou POST

GET prend en charge toutes les fonctionnalités mais limite la spécification à 6 Ko, et génère toujours du PNG sans clé jusqu'à 1600 px. Envoyez le même JSON à POST /v1/renders pour une charge utile plus importante, une clé pour un canevas plus grand, ou une clé Pro pour du SVG.

Modifiable ensuite

Chaque image porte un en-tête Link qui ouvre le rendu dans Ultimaps Studio comme une véritable carte. Les rendus sans clé s'ouvrent pour toute personne disposant du lien. Un rendu avec clé ne s'ouvre que pour une personne connectée à l'espace de travail de cette clé.

Recettes

Six requêtes complètes. Chacune est validée par rapport au schéma de requête en direct dans l'intégration continue, vous pouvez donc les copier telles quelles, remplacer le mapId et les valeurs, et c'est parti. Chaque image est la réponse renvoyée par la requête qui l'accompagne, filigrane inclus, sur le niveau gratuit sans clé.

Mettre en évidence quelques régions

La requête utile la plus simple. Vous nommez des régions et attribuez une couleur à chacune. Tout le reste prend les valeurs par défaut de la carte.

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

Carte des États-Unis intitulée « Où nous opérons », avec la Californie en bleu, le Texas en orange et New York en vert, chaque autre État dans le thème par défaut et étiqueté avec son abréviation

• Les clés de région sont flexibles. « US-CA », « California » et « CA » atteignent tous la même région.
• Les couleurs sont des chaînes hexadécimales. Les régions que vous omettez conservent le thème par défaut.
• « style.labels.show » affiche le nom de chaque région. Il n'existe aucun moyen d'étiqueter uniquement les régions que vous avez colorées.

Ouvrir ce rendu dans un nouvel onglet

Choroplèthe à partir de nombres

Donnez des valeurs brutes à l'API et elle choisit les classes, les couleurs et la légende. C'est la requête que la plupart des gens veulent.

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

Carte choroplèthe de la population des États américains en 2025, ombrée sur cinq classes quantiles bleues avec les étiquettes de coupure dans une légende et chaque valeur imprimée en millions sur son État

• Omettez « type », « classes » et « method » et l'API les détecte à partir de vos données.
• « palette » accepte l'une des 26 palettes intégrées. « noDataColor » peint les régions que vos données ne couvrent pas.
• « format » contrôle les étiquettes de coupure dans la légende, pas le format de l'image.

Ouvrir ce rendu dans un nouvel onglet

Repères

Marqueurs de latitude et de longitude. Les repères se composent avec tout le reste, vous pouvez donc les déposer sur une choroplèthe ou sur une carte simple.

La sortie SVG nécessite une clé Pro. Supprimez « format » pour du PNG sur n'importe quel niveau.

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

Affiché en PNG — la requête demande du SVG. Même carte dans les deux cas.

• Chaque repère a sa propre couleur, son côté d'étiquette et sa visibilité d'étiquette.
• Les repères sont placés par coordonnées. L'API ne géocode pas les adresses.

Le SVG nécessite une clé Pro. Le chemin GET sans clé ne renvoie que du PNG.

Vérifier une requête avant de la rendre

L'exécution à sec renvoie du JSON au lieu d'une image : quelles clés ont correspondu, lesquelles non, ce qui a été corrigé et quelles coupures ont été obtenues. Cela ne consomme pas de quota.

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

• La faute de frappe « Calfornia » est corrigée en California. « Atlantis » revient sans correspondance.
• Utilisez ceci pendant que vous connectez vos données, puis désactivez « dryRun ».

Ouvrir le JSON d'exécution à sec renvoyé

Échouer sur les mauvaises clés plutôt que de deviner

Par défaut, les clés sans correspondance sont ignorées. Définissez « onUnmatched » sur « error » et l'API renvoie une erreur 400 avec des suggestions par clé, ce qui est ce que vous voulez dans un travail planifié.

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

• L'erreur 400 est un document de problème RFC 9457. Faites une branche sur « code », pas sur le message.

Ouvrir l'erreur 400 renvoyée

Référence complète des champs, y compris les 26 palettes, les quatre méthodes de coupure, les thèmes, les couches supplémentaires et le formatage des nombres : la référence API.

Cartes que vous pouvez générer

187 cartes, des cartes du monde et des continents jusqu'aux comtés américains et aux zones de codes ZIP. Le mapId est le slug de la carte sur ce site, et il ne change jamais une fois publié.

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

Clés et limites

Une clé augmente les limites de débit et la taille du canevas. Une clé Pro supprime le filigrane et débloque le SVG. Créez-en une dans Studio sous Workspace, puis API. Les clés ne sont affichées qu'une fois.

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

Niveau	Authentification	Formats	Attribution	Canevas	Limite de débit	Mensuel
Sans clé	aucune	PNG	filigrane complet	≤ 1600 px, échelle 1	30/heure par IP, rafale 5/min	aucun plafond mensuel
Clé gratuite	Bearer um_live_…	PNG	filigrane complet	≤ 1600 px, échelle ≤ 2	10/min, 50/jour	500 rendus
Clé Pro	Bearer um_live_…	PNG, SVG	aucun	≤ 4000 px, échelle ≤ 4	30/min, 1 000/jour	5 000 rendus

Le quota mensuel est un état de facturation et renvoie 402, jamais réessayable. Les limites de débit et de concurrence renvoient 429 avec Retry-After. Les exécutions à sec ne consomment jamais de quota. Consultez GET /v1/usage pour savoir où vous en êtes.

Depuis Claude, Codex ou tout client MCP

Demandez une carte dans le chat et l'image revient dans la conversation. @ultimaps/mcp est cette API sous forme d'outils MCP sur stdio, sans compte : render_map, list_maps et get_map_regions.

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

Les clients qui lisent un fichier de configuration prennent les deux mêmes valeurs. C'est claude_desktop_config.json.

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

Laissez ULTIMAPS_API_KEY vide pour le niveau sans clé, mêmes limites que le tableau ci-dessus, ou remplissez-le pour le quota et la sortie de votre plan.

Pas dans v1

v1 génère des images. Il ne fait rien de tout cela :

• Publication de cartes interactives ou intégrables
• Sortie PDF
• Géocodage d'adresses en coordonnées
• Lecture de la géométrie derrière une carte

Si vous avez besoin de l'un de ces éléments, dites-nous lequel et nous vous ferons savoir quand il existera. Ce que les gens demandent ici est ce que nous construisons ensuite.

Référence

Référence API

Chaque point de terminaison et champ, en direct par rapport à l'API en cours d'exécution.

Codes d'erreur

Chaque code, son statut HTTP, et s'il faut réessayer.

openapi.json

Contrat OpenAPI 3.1. Générez un client à partir de celui-ci.

llms-full.txt

Toute l'API sous forme d'un seul fichier texte brut pour les agents de codage.

@ultimaps/mcp

Le serveur MCP. Trois outils, stdio, aucun compte nécessaire.

Foire aux questions

Existe-t-il une API choroplèthe ?

Oui, c'est la fonction principale de cette API. Envoyez un ensemble de clés de région et de nombres et vous obtenez une carte classée, colorée, avec légende au format PNG. L'API choisit la méthode de coupure, le nombre de classes et la palette à partir de vos données, sauf si vous les définissez vous-même.

Comment générer une image cartographique à partir d'une URL ?

Placez votre JSON de requête dans le paramètre de requête spec de GET /v1/renders et la réponse est le PNG lui-même. Cette URL fonctionne dans une balise img, une image markdown, un bloc d'image Notion ou une formule IMAGE() de Google Sheets, sans clé et sans compte.

Puis-je utiliser l'API d'images cartographiques sans clé API ?

Oui. Le niveau sans clé génère du PNG jusqu'à 1600 par 1600 pixels à 30 rendus par heure par IP, avec un filigrane Ultimaps. Une clé augmente les limites, et une clé Pro supprime le filigrane et ajoute le SVG.

Est-ce une API de cartes de comtés ? Puis-je obtenir les limites de comtés ?

Elle génère des cartes de comtés sous forme d'images, y compris les 3 143 comtés américains, mais elle ne fournit pas la géométrie des limites. Si vous avez besoin de GeoJSON ou de shapefiles à traiter vous-même, utilisez Census TIGER ou Natural Earth à la place. Cette API renvoie des images.

Géocode-t-elle les adresses ?

Non. Les repères sont placés par latitude et longitude, et les couleurs des régions sont assorties par clé ou nom de région. Le géocodage est une fonctionnalité de Studio, pas de l'API.

Existe-t-il un serveur MCP ?

Oui. Installez @ultimaps/mcp dans Claude Code, Codex, Claude Desktop, Cursor, VS Code ou tout autre client MCP et il expose render_map, list_maps et get_map_regions sur stdio. Il fonctionne sur Node.js 20 ou plus récent, ne nécessite aucun compte, et lit ULTIMAPS_API_KEY lorsque vous en définissez une.

Puis-je obtenir du SVG au lieu du PNG ?

Oui, avec une clé Pro. Définissez output.format sur svg. Les clés sans clé et gratuites renvoient du PNG.

Que se passe-t-il si mes noms de régions ne correspondent pas ?

Les clés sont assorties sans tenir compte de la casse aux codes de région, titres, alias courants et titres normalisés, donc US-CA, California et CA atteignent tous la même région, et les fautes de frappe sans ambiguïté sont corrigées et signalées. Par défaut, les clés sans correspondance sont ignorées et signalées dans un en-tête de réponse. Définissez onUnmatched sur error et la requête échoue avec des suggestions par clé à la place.

Comment mettre une carte dans un README GitHub ?

Utilisez l'URL GET sans clé comme image markdown. GitHub la proxifie via Camo, et comme l'API envoie un en-tête de cache de 24 heures, l'image se rafraîchit quotidiennement plutôt que de se figer.

Puis-je générer une carte côté serveur ?

Oui. Chaque rendu se produit sur nos serveurs, donc il n'y a pas de navigateur, pas de Chrome sans tête et pas de bibliothèque cartographique dans votre pile technique. Un seul appel HTTP renvoie l'image terminée.