Ultimaps MCP

API de imágenes de mapas

Datos de entrada, imagen de mapa de salida. Una sola URL renderiza un mapa de coropletas, de categorías o de pines de cualquier país, estado, condado o área ZIP como PNG. Sin cuenta, sin clave, sin biblioteca de mapas en tu 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

Esa es toda la solicitud. El parámetro spec es JSON codificado en URL, y la respuesta es la imagen en sí.

Renderizado en vivo por la URL de la izquierda, en caché durante 24 horas.

Se integra en cualquier lugar

La URL devuelve la imagen, así que funciona en una etiqueta <img>, un README, una página de Notion o una celda de Google Sheets.

GET o POST

GET admite todas las funciones pero limita la especificación a 6KB, y siempre renderiza PNG sin clave de hasta 1600px. Envía el mismo JSON a POST /v1/renders para una carga mayor, una clave para un lienzo más grande, o una clave Pro para SVG.

Editable después

Cada imagen lleva una cabecera Link que abre el render en Ultimaps Studio como un mapa real. Los renders sin clave se abren para cualquiera con el enlace. Un render con clave se abre solo para alguien con sesión iniciada en el espacio de trabajo de esa clave.

Recetario

Seis solicitudes completas. Todas se validan contra el esquema de solicitudes en vivo en CI, así que puedes copiarlas tal cual, cambiar el mapId y los valores, y listo. Cada imagen es la respuesta que devolvió la solicitud junto a ella, marca de agua incluida, en el nivel gratuito sin clave.

Resalta algunas regiones

La solicitud útil más sencilla. Nombra regiones y dale a cada una un color. Todo lo demás toma el valor predeterminado del mapa.

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

Mapa de Estados Unidos titulado "Where we operate", con California en azul, Texas en naranja y Nueva York en verde, todos los demás estados con el valor predeterminado del tema y etiquetados con su abreviatura

• Las claves de región son flexibles. "US-CA", "California" y "CA" llegan todos a la misma región.
• Los colores son cadenas hexadecimales. Las regiones que omitas conservan el valor predeterminado del tema.
• "style.labels.show" imprime el nombre de cada región. Para dejar algunas regiones sin etiqueta, lista sus claves en "style.labels.hide".

Abrir este render en una pestaña nueva

Coropletas a partir de números

Dale valores brutos a la API y ella elige las clases, los colores y la leyenda. Esta es la solicitud que la mayoría de la gente quiere.

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

Mapa de coropletas de la población de los estados de EE. UU. en 2025, sombreado en cinco clases de cuantiles azules con las etiquetas de corte en una leyenda y cada valor impreso en millones sobre su estado

• Omite "type", "classes" y "method" y la API los detecta a partir de tus datos.
• "palette" acepta cualquiera de las 26 paletas integradas. "noDataColor" pinta las regiones que tus datos no cubren, y "noData" añade una fila "No data" para ellas en la leyenda.
• "legend.title" nombra qué miden los colores. Dale uno a cada leyenda de datos.
• "format" controla cómo se imprimen los números en la leyenda y en el mapa, no el formato de la imagen.
• "style.labels.content" es "value" aquí. "name_value" imprime el nombre del estado con su número debajo.

Abrir este render en una pestaña nueva

Pines

Marcadores de latitud y longitud. Los pines se combinan con todo lo demás, así que puedes colocarlos sobre un mapa de coropletas o sobre un mapa simple.

La salida SVG requiere una clave Pro. Omite "format" para obtener PNG en cualquier nivel.

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

Mostrado como PNG — la solicitud pide SVG. El mismo mapa en cualquier caso.

• Cada pin tiene su propio color, lado de la etiqueta y visibilidad de la etiqueta.
• Los pines se colocan por coordenadas. La API no geocodifica direcciones.

SVG requiere una clave Pro. La ruta GET sin clave devuelve solo PNG.

Comprueba una solicitud antes de renderizarla

La ejecución en seco devuelve JSON en lugar de una imagen: qué claves coincidieron, cuáles no, qué se corrigió y cómo quedaron los cortes. No consume cuota.

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

• El error tipográfico "Calfornia" vuelve corregido a California. "Atlantis" vuelve sin coincidencia.
• Úsalo mientras conectas tus datos, luego desactiva "dryRun".

Abrir el JSON de ejecución en seco que devuelve esto

Falla con claves incorrectas en lugar de adivinar

Por defecto, las claves sin coincidencia se omiten. Establece "onUnmatched" en "error" y la API devuelve un 400 con sugerencias por clave, que es lo que quieres en una tarea programada.

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

• El 400 es un documento de problema RFC 9457. Ramifica según "code", no según el mensaje.

Abrir el 400 que devuelve esto

Referencia completa de campos, incluidas las 26 paletas, los cuatro métodos de cortes, los temas, las capas adicionales y el formato de números: la referencia de la API.

Mapas que puedes renderizar

189 mapas, desde mapas del mundo y de continentes hasta condados de EE. UU. y áreas de códigos ZIP. El mapId es el slug del mapa en este sitio, y nunca cambia una vez publicado.

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

Claves y límites

Una clave eleva los límites de velocidad y el tamaño del lienzo. Una clave Pro elimina la marca de agua y desbloquea SVG. Crea una en Studio en Workspace, luego API. Las claves se muestran una sola vez.

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

Nivel	Autenticación	Formatos	Atribución	Lienzo	Límite de velocidad	Mensual
Sin clave	ninguna	PNG	marca de agua completa	≤ 1600 px, escala 1	30/hora por IP, ráfaga 5/min	sin tope mensual
Clave gratuita	Bearer um_live_…	PNG	marca de agua completa	≤ 1600 px, escala ≤ 2	10/min, 50/día	500 renders
Clave Pro	Bearer um_live_…	PNG, SVG	ninguna	≤ 4000 px, escala ≤ 4	30/min, 1.000/día	5.000 renders

La cuota mensual es un estado de facturación y devuelve 402, nunca reintentable. Los límites de velocidad y concurrencia devuelven 429 con Retry-After. Las ejecuciones en seco nunca consumen cuota. Consulta GET /v1/usage para saber en qué punto estás.

Desde ChatGPT, Claude o cualquier cliente MCP

Usa esta API desde ChatGPT, Claude, Cursor o cualquier cliente MCP y recibe el mapa de vuelta en el chat. Añade https://api.ultimaps.com/mcp por URL, o ejecuta el paquete @ultimaps/mcp en tu ordenador. Ninguno necesita una cuenta.

Configurar el servidor MCP de Ultimaps

No incluido en v1

v1 renderiza imágenes. No hace nada de esto:

• Publicar mapas interactivos o incrustables
• Salida en PDF
• Geocodificar direcciones a coordenadas
• Leer de vuelta la geometría detrás de un mapa

Si necesitas alguna de estas, dinos cuál y te avisaremos cuando exista. Lo que la gente pide aquí es lo que construimos después.

Referencia

Referencia de la API

Cada endpoint y campo, en vivo contra la API en ejecución.

Códigos de error

Cada código, su estado HTTP y si reintentarlo.

openapi.json

Contrato OpenAPI 3.1. Genera un cliente a partir de él.

llms-full.txt

Toda la API en un solo archivo de texto plano para agentes de programación.

Servidor MCP

Añade https://api.ultimaps.com/mcp por URL, o ejecuta @ultimaps/mcp localmente. No se necesita cuenta.

Preguntas frecuentes

¿Existe una API de coropletas?

Sí, eso es lo principal que hace esta API. Envía un conjunto de claves de región y números y recibes de vuelta un mapa clasificado, coloreado y con leyenda como PNG. La API elige el método de cortes, el número de clases y la paleta a partir de tus datos a menos que los establezcas tú mismo.

¿Cómo genero una imagen de mapa a partir de una URL?

Pon tu JSON de solicitud en el parámetro de consulta spec de GET /v1/renders y la respuesta es el PNG en sí. Esa URL funciona en una etiqueta img, una imagen de markdown, un bloque de imagen de Notion o una fórmula IMAGE() de Google Sheets, sin clave y sin cuenta.

¿Puedo usar la API de imágenes de mapas sin una clave de API?

Sí. El nivel sin clave renderiza PNG de hasta 1600 por 1600 píxeles a 30 renders por hora por IP, con una marca de agua de Ultimaps. Una clave eleva los límites, y una clave Pro elimina la marca de agua y añade SVG.

¿Es esta una API de mapas de condados? ¿Puedo obtener límites de condados de ella?

Renderiza mapas de condados como imágenes, incluidos los 3.143 condados de EE. UU., pero no sirve geometría de límites. Si necesitas GeoJSON o shapefiles para procesarlos tú mismo, usa Census TIGER o Natural Earth en su lugar. Esta API devuelve imágenes.

¿Geocodifica direcciones?

No. Los pines se colocan por latitud y longitud, y los colores de las regiones se emparejan por clave o nombre de región. La geocodificación es una función de Studio, no de la API.

¿Existe un servidor MCP?

Sí. Añade https://api.ultimaps.com/mcp por URL en ChatGPT, Claude o cualquier cliente MCP, o ejecuta el paquete @ultimaps/mcp localmente, y tu asistente obtiene render_map, list_maps y get_map_regions sin necesidad de cuenta. Los pasos de configuración para cada cliente están en ultimaps.com/mcp/.

¿Puedo obtener SVG en lugar de PNG?

Sí, con una clave Pro. Establece output.format en svg. Las claves sin clave y gratuitas devuelven PNG.

¿Qué pasa si los nombres de mis regiones no coinciden?

Las claves se emparejan sin distinguir mayúsculas y minúsculas contra códigos de región, títulos, alias comunes y títulos normalizados, así que US-CA, California y CA llegan todos a la misma región, y los errores tipográficos inequívocos se corrigen y se reportan. Por defecto, las claves sin coincidencia se omiten y se reportan en una cabecera de respuesta. Establece onUnmatched en error y la solicitud falla con sugerencias por clave en su lugar.

¿Cómo pongo un mapa en un README de GitHub?

Usa la URL GET sin clave como imagen de markdown. GitHub la redirige a través de Camo, y como la API envía una cabecera de caché de 24 horas, la imagen se actualiza a diario en lugar de congelarse.

¿Puedo renderizar un mapa en el servidor?

Sí. Cada render ocurre en nuestros servidores, así que no hay navegador, ni Chrome sin interfaz, ni biblioteca de mapas en tu stack. Una sola llamada HTTP devuelve la imagen terminada.