Ultimaps MCP

API de Imagens de Mapas

Dados entram, imagem de mapa sai. Uma URL renderiza um mapa coroplético, de categorias ou de pinos de qualquer país, estado, condado ou área de CEP como PNG. Sem conta, sem chave, sem biblioteca de mapas na sua 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

Essa é a requisição inteira. O parâmetro spec é JSON codificado em URL, e a resposta é a própria imagem.

Renderizado ao vivo pela URL à esquerda, com cache de 24 horas.

Integra em qualquer lugar

A URL retorna a imagem, então funciona em uma tag <img>, um README, uma página do Notion ou uma célula do Google Sheets.

GET ou POST

GET aceita todos os recursos, mas limita a especificação a 6KB, e sempre renderiza PNG sem chave em até 1600px. Envie o mesmo JSON para POST /v1/renders para um payload maior, uma chave para um canvas maior, ou uma chave Pro para SVG.

Editável depois

Toda imagem carrega um cabeçalho Link que abre a renderização no Ultimaps Studio como um mapa real. Renderizações sem chave abrem para qualquer pessoa com o link. Uma renderização com chave abre apenas para alguém conectado ao workspace daquela chave.

Livro de receitas

Seis requisições completas. Cada uma é validada contra o schema de requisição ao vivo em CI, então você pode copiá-las como estão, trocar o mapId e os valores, e pronto. Cada imagem é a resposta que a requisição ao lado retornou, com marca d'água incluída, no nível gratuito sem chave.

Destacar algumas regiões

A requisição útil mais simples. Você nomeia regiões e dá a cada uma uma cor. Todo o resto usa o padrão do 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 dos Estados Unidos intitulado "Onde operamos", com Califórnia em azul, Texas em laranja e Nova York em verde, todos os outros estados no tema padrão e rotulados com sua abreviação

• As chaves de região são flexíveis. "US-CA", "California" e "CA" alcançam a mesma região.
• Cores são strings hexadecimais. Regiões que você deixar de fora mantêm o padrão do tema.
• "style.labels.show" imprime o nome de cada região. Não há como rotular apenas as regiões que você coloriu.

Abrir esta renderização em uma nova aba

Coroplético a partir de números

Dê valores brutos à API e ela escolhe as classes, as cores e a legenda. Esta é a requisição que a maioria das pessoas quer.

{
  "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 coroplético da população dos estados dos EUA em 2025, sombreado em cinco classes quantílicas azuis com os rótulos de quebra na legenda e cada valor impresso em milhões em seu estado

• Deixe de fora "type", "classes" e "method" e a API os detecta a partir dos seus dados.
• "palette" aceita qualquer uma das 26 paletas integradas. "noDataColor" pinta regiões que seus dados não cobrem.
• "format" controla os rótulos de quebra na legenda, não o formato da imagem.

Abrir esta renderização em uma nova aba

Pinos

Marcadores de latitude e longitude. Pinos compõem com todo o resto, então você pode colocá-los sobre um coroplético ou sobre um mapa simples.

Saída SVG precisa de chave Pro. Remova "format" para PNG em qualquer nível.

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

Exibido como PNG — a requisição pede SVG. Mesmo mapa de qualquer forma.

• Cada pino tem sua própria cor, lado do rótulo e visibilidade do rótulo.
• Pinos são posicionados por coordenadas. A API não geocodifica endereços.

SVG precisa de chave Pro. O caminho GET sem chave retorna apenas PNG.

Verifique uma requisição antes de renderizá-la

Dry run retorna JSON em vez de imagem: quais das suas chaves corresponderam, quais não, o que foi corrigido e como ficaram as quebras. Não consome cota.

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

• O erro de digitação "Calfornia" volta corrigido para California. "Atlantis" volta sem correspondência.
• Use isso enquanto conecta seus dados, depois desative "dryRun".

Abrir o JSON do dry-run que isso retorna

Falhe em chaves ruins em vez de adivinhar

Por padrão, chaves sem correspondência são ignoradas. Defina "onUnmatched" como "error" e a API retorna um 400 com sugestões por chave, que é o que você quer em um job agendado.

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

• O 400 é um documento de problema RFC 9457. Ramifique em "code", não na mensagem.

Abrir o 400 que isso retorna

Referência completa de campos, incluindo todas as 26 paletas, os quatro métodos de quebra, temas, camadas extras e formatação de números: a referência da API.

Mapas que você pode renderizar

187 mapas, de mapas mundiais e continentais até condados dos EUA e áreas de CEP. O mapId é o slug do mapa neste site, e nunca muda depois de publicado.

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

Chaves e limites

Uma chave aumenta os limites de taxa e o tamanho do canvas. Uma chave Pro remove a marca d'água e desbloqueia SVG. Crie uma no Studio em Workspace, depois API. Chaves são mostradas apenas uma 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

Nível	Autenticação	Formatos	Atribuição	Canvas	Limite de taxa	Mensal
Sem chave	nenhuma	PNG	marca d'água completa	≤ 1600 px, escala 1	30/hora por IP, rajada 5/min	sem limite mensal
Chave gratuita	Bearer um_live_…	PNG	marca d'água completa	≤ 1600 px, escala ≤ 2	10/min, 50/dia	500 renderizações
Chave Pro	Bearer um_live_…	PNG, SVG	nenhuma	≤ 4000 px, escala ≤ 4	30/min, 1.000/dia	5.000 renderizações

A cota mensal é um estado de faturamento e retorna 402, nunca repetível. Limites de taxa e concorrência retornam 429 com Retry-After. Dry runs nunca consomem cota. Verifique GET /v1/usage para saber sua situação.

Do Claude, Codex ou qualquer cliente MCP

Peça um mapa no chat e a imagem volta na conversa. @ultimaps/mcp é esta API como ferramentas MCP via stdio, sem conta: render_map, list_maps e get_map_regions.

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

Clientes que leem um arquivo de configuração aceitam os mesmos dois valores. Isto é claude_desktop_config.json.

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

Deixe ULTIMAPS_API_KEY vazio para o nível sem chave, mesmos limites da tabela acima, ou preencha para a cota e saída do seu plano.

Não está na v1

A v1 renderiza imagens. Ela não faz nada disso:

• Publicar mapas interativos ou incorporáveis
• Saída em PDF
• Geocodificar endereços para coordenadas
• Ler de volta a geometria por trás de um mapa

Se você precisa de um desses, conte para nós qual e avisaremos quando existir. O que as pessoas pedem aqui é o que construímos em seguida.

Referência

Referência da API

Cada endpoint e campo, ao vivo contra a API em execução.

Códigos de erro

Cada código, seu status HTTP e se deve repetir.

openapi.json

Contrato OpenAPI 3.1. Gere um cliente a partir dele.

llms-full.txt

Toda a API como um único arquivo de texto simples para agentes de codificação.

@ultimaps/mcp

O servidor MCP. Três ferramentas, stdio, sem necessidade de conta.

Perguntas Frequentes

Existe uma API de coroplético?

Sim, essa é a principal função desta API. Envie um conjunto de chaves de região e números e você recebe um mapa classificado, colorido, com legenda como PNG. A API escolhe o método de quebra, a quantidade de classes e a paleta a partir dos seus dados, a menos que você os defina.

Como gero uma imagem de mapa a partir de uma URL?

Coloque seu JSON de requisição no parâmetro de consulta spec de GET /v1/renders e a resposta é o próprio PNG. Essa URL funciona em uma tag img, uma imagem markdown, um bloco de imagem do Notion ou uma fórmula IMAGE() do Google Sheets, sem chave e sem conta.

Posso usar a API de imagens de mapas sem uma chave de API?

Sim. O nível sem chave renderiza PNG de até 1600 por 1600 pixels a 30 renderizações por hora por IP, com marca d'água da Ultimaps. Uma chave aumenta os limites, e uma chave Pro remove a marca d'água e adiciona SVG.

Esta é uma API de mapas de condados? Posso obter limites de condados dela?

Ela renderiza mapas de condados como imagens, incluindo todos os 3.143 condados dos EUA, mas não fornece geometria de limites. Se você precisa de GeoJSON ou shapefiles para processar você mesmo, use Census TIGER ou Natural Earth. Esta API retorna imagens.

Ela geocodifica endereços?

Não. Pinos são posicionados por latitude e longitude, e cores de região são correspondidas por chave ou nome de região. Geocodificação é um recurso do Studio, não da API.

Existe um servidor MCP?

Sim. Instale @ultimaps/mcp no Claude Code, Codex, Claude Desktop, Cursor, VS Code ou qualquer outro cliente MCP e ele expõe render_map, list_maps e get_map_regions via stdio. Ele roda em Node.js 20 ou mais recente, não precisa de conta e lê ULTIMAPS_API_KEY quando você define uma.

Posso obter SVG em vez de PNG?

Sim, com uma chave Pro. Defina output.format como svg. Chaves gratuitas e sem chave retornam PNG.

O que acontece se meus nomes de região não corresponderem?

Chaves são correspondidas sem diferenciar maiúsculas de minúsculas contra códigos de região, títulos, aliases comuns e títulos normalizados, então US-CA, California e CA alcançam a mesma região, e erros de digitação inequívocos são corrigidos e relatados. Por padrão, chaves sem correspondência são ignoradas e relatadas em um cabeçalho de resposta. Defina onUnmatched como error e a requisição falha com sugestões por chave.

Como coloco um mapa em um README do GitHub?

Use a URL GET sem chave como uma imagem markdown. O GitHub a proxy através do Camo, e como a API envia um cabeçalho de cache de 24 horas, a imagem é atualizada diariamente em vez de congelar.

Posso renderizar um mapa no lado do servidor?

Sim. Toda renderização acontece em nossos servidores, então não há navegador, Chrome headless ou biblioteca de mapas na sua stack. Uma única chamada HTTP retorna a imagem finalizada.