Ultimaps MCP

API de Mapas de Imagen

Datos de entrada, imagen de mapa de salida. Una URL genera un mapa de coropletas, de categorías o de pines de cualquier país, estado, condado o área de código postal como PNG. Sin cuenta, sin clave, sin librería 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 propia imagen.

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

Se integra en cualquier lugar

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

GET o POST

GET acepta 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 un payload más grande, una clave para un lienzo más grande, o una clave Pro para SVG.

Editable después

Cada imagen lleva un encabezado Link que abre el renderizado en Ultimaps Studio como un mapa real. Los renderizados sin clave se abren para cualquier persona con el enlace. Un renderizado con clave se abre solo para alguien conectado al espacio de trabajo de esa clave.

Recetario

Seis solicitudes completas. Cada una está validada 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 a su lado, con marca de agua incluida, en el nivel gratuito sin clave.

Resaltar algunas regiones

La solicitud útil más simple. Nombras regiones y les das un color a cada una. 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 los Estados Unidos titulado "Where we operate", con California en azul, Texas en naranja y Nueva York en verde, cada otro estado en el tema predeterminado y etiquetado con su abreviatura

• Las claves de región son flexibles. "US-CA", "California" y "CA" llegan a la misma región.
• Los colores son cadenas hexadecimales. Las regiones que omitas mantienen el tema predeterminado.
• "style.labels.show" imprime el nombre de cada región. No hay forma de etiquetar solo las regiones que coloreaste.

Abrir este renderizado en una nueva pestaña

Coropletas a partir de números

Dale a la API valores brutos 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",
    "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

Mapa de coropletas de la población estatal 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.
• "format" controla las etiquetas de corte en la leyenda, no el formato de imagen.

Abrir este renderizado en una nueva pestaña

Pines

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

La salida SVG necesita una clave Pro. Omite "format" para 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. Mismo mapa de cualquier manera.

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

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

Verifica 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" se devuelve corregido a California. "Atlantis" se devuelve sin coincidencia.
• Usa esto mientras conectas tus datos, luego desactiva "dryRun".

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

Fallar con claves incorrectas en lugar de adivinar

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

{
  "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 en "code", no en el mensaje.

Abrir el 400 que esto devuelve

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

Mapas que puedes renderizar

187 mapas, desde mapas mundiales y continentales hasta condados de EE. UU. y áreas de códigos postales. El mapId es el slug del mapa en este sitio, y nunca cambia una vez publicado.

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

Claves y límites

Una clave aumenta 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 bajo 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",
      "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

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 renderizados
Clave Pro	Bearer um_live_…	PNG, SVG	ninguna	≤ 4000 px, escala ≤ 4	30/min, 1,000/día	5,000 renderizados

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 ver tu situación.

Desde Claude, Codex o cualquier cliente MCP

Pide un mapa en el chat y la imagen vuelve en la conversación. @ultimaps/mcp es esta API como herramientas MCP sobre stdio, sin cuenta: render_map, list_maps y get_map_regions.

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

Los clientes que leen un archivo de configuración toman los mismos dos valores. Esto es claude_desktop_config.json.

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

Deja ULTIMAPS_API_KEY vacío para el nivel sin clave, mismos límites que la tabla anterior, o complétalo para la cuota y salida de tu plan.

No en v1

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

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

Si necesitas una de estas cosas, 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 se debe reintentar.

openapi.json

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

llms-full.txt

Toda la API como un solo archivo de texto plano para agentes de codificación.

@ultimaps/mcp

El servidor MCP. Tres herramientas, stdio, sin necesidad de cuenta.

Preguntas frecuentes

¿Hay una API de coropletas?

Sí, esa es la función principal de esta API. Publica un conjunto de claves de región y números y obtienes un mapa clasificado, coloreado y con leyenda como PNG. La API elige el método de corte, el número de clases y la paleta a partir de tus datos a menos que los configures tú mismo.

¿Cómo genero una imagen de mapa desde una URL?

Pon tu JSON de solicitud en el parámetro de consulta spec de GET /v1/renders y la respuesta es el propio PNG. 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 renderizados por hora por IP, con una marca de agua de Ultimaps. Una clave aumenta 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, incluyendo 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. Esta API devuelve imágenes.

¿Geocodifica direcciones?

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

¿Hay un servidor MCP?

Sí. Instala @ultimaps/mcp en Claude Code, Codex, Claude Desktop, Cursor, VS Code o cualquier otro cliente MCP y expone render_map, list_maps y get_map_regions sobre stdio. Se ejecuta en Node.js 20 o superior, no necesita cuenta, y lee ULTIMAPS_API_KEY cuando configuras una.

¿Puedo obtener SVG en lugar de PNG?

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

¿Qué pasa si mis nombres de región no coinciden?

Las claves se emparejan sin distinguir mayúsculas contra códigos de región, títulos, alias comunes y títulos normalizados, así que US-CA, California y CA llegan a la misma región, y los errores tipográficos inequívocos se corrigen y reportan. Por defecto, las claves sin coincidencia se omiten y se reportan en un encabezado de respuesta. Configura onUnmatched a 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 proxifica a través de Camo, y como la API envía un encabezado de caché de 24 horas, la imagen se actualiza diariamente en lugar de congelarse.

¿Puedo renderizar un mapa en el servidor?

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