Ultimaps MCP

API de Imagem de Mapa

Dados entram, imagem de mapa sai. Uma URL renderiza um mapa coroplético, de categoria 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, em cache por 24 horas.

Encaixa 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 spec a 6KB, e sempre renderiza PNG sem chave de até 1600px. Envie o mesmo JSON para POST /v1/renders para um payload maior, uma chave para uma tela 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 de verdade. Renderizações sem chave abrem para qualquer pessoa com o link. Uma renderização com chave abre apenas para alguém autenticado no workspace daquela chave.

Livro de Receitas

Seis requisições completas. Cada uma é validada contra o schema de requisição ao vivo na 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, marca d'água incluída, no nível gratuito sem chave.

Destaque algumas regiões

A requisição útil mais simples. Você nomeia regiões e dá uma cor a cada uma. Todo o resto assume 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 na cor padrão do tema e rotulados com sua abreviação

• As chaves de região são flexíveis. "US-CA", "California" e "CA" chegam todos à mesma região.
• As cores são strings hexadecimais. Regiões que você omitir mantêm o padrão do tema.
• "style.labels.show" imprime o nome de cada região. Para deixar algumas regiões sem rótulo, liste suas chaves em "style.labels.hide".

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

• Omita "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, e "noData" adiciona uma linha "Sem dados" para elas na legenda.
• "legend.title" nomeia o que as cores medem. Dê um a toda legenda de dados.
• "format" controla como os números são impressos na legenda e no mapa, não o formato da imagem.
• "style.labels.content" é "value" aqui. "name_value" imprime o nome do estado com seu número abaixo.

Abra esta renderização em uma nova aba

Pinos

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

A saída SVG exige uma 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. O mesmo mapa de qualquer forma.

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

SVG exige uma chave Pro. O caminho GET sem chave retorna apenas PNG.

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

O dry run retorna JSON em vez de uma imagem: quais das suas chaves corresponderam, quais não corresponderam, o que foi corrigido e como as quebras ficaram. 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 isto enquanto você conecta seus dados, depois desligue "dryRun".

Abra o JSON de dry-run que isto retorna

Falhe em chaves inválidas 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 por "code", não pela mensagem.

Abra o 400 que isto 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

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

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

Chaves e limites

Uma chave eleva os limites de taxa e o tamanho da tela. Uma chave Pro remove a marca d'água e desbloqueia SVG. Crie uma no Studio em Workspace, depois API. As chaves são exibidas uma única 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

Nível	Autenticação	Formatos	Atribuição	Tela	Limite de taxa	Mensal
Sem chave	nenhuma	PNG	marca d'água completa	≤ 1600 px, escala 1	30/hora por IP, burst 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 cobrança 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 ChatGPT, Claude ou qualquer cliente MCP

Use esta API do ChatGPT, Claude, Cursor ou qualquer cliente MCP e receba o mapa de volta no chat. Adicione https://api.ultimaps.com/mcp por URL, ou execute o pacote @ultimaps/mcp no seu computador. Nenhum dos dois precisa de conta.

Configure o servidor Ultimaps MCP

Fora da v1

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

• 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 algo disto, diga-nos qual e avisaremos quando existir. O que as pessoas pedem aqui é o que construímos a seguir.

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 ser repetido.

openapi.json

Contrato OpenAPI 3.1. Gere um cliente a partir dele.

llms-full.txt

A API inteira como um único arquivo de texto simples para agentes de código.

Servidor MCP

Adicione https://api.ultimaps.com/mcp por URL, ou execute @ultimaps/mcp localmente. Sem necessidade de conta.

Perguntas Frequentes

Existe uma API de coroplético?

Sim, é a principal coisa que esta API faz. Envie um conjunto de chaves de região e números e você recebe de volta um mapa classificado, colorido e com legenda como PNG. A API escolhe o método de quebra, o número 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 imagem de mapa 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 uma marca d'água Ultimaps. Uma chave eleva os limites, e uma chave Pro remove a marca d'água e adiciona SVG.

Esta é uma API de mapa de condados? Posso obter limites de condados a partir dela?

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

Ela faz geocodificação de endereços?

Não. Os pinos são posicionados por latitude e longitude, e as cores das regiões são correspondidas por chave ou nome de região. A geocodificação é um recurso do Studio, não da API.

Existe um servidor MCP?

Sim. Adicione https://api.ultimaps.com/mcp por URL no ChatGPT, Claude ou qualquer cliente MCP, ou execute o pacote @ultimaps/mcp localmente, e seu assistente recebe render_map, list_maps e get_map_regions sem necessidade de conta. Os passos de configuração para cada cliente estão em ultimaps.com/mcp/.

Posso obter SVG em vez de PNG?

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

O que acontece se os nomes das minhas regiões não corresponderem?

As chaves são correspondidas sem distinção de maiúsculas e minúsculas contra códigos de região, títulos, aliases comuns e títulos normalizados, então US-CA, California e CA chegam todos à mesma região, e erros de digitação inequívocos são corrigidos e reportados. Por padrão, chaves sem correspondência são ignoradas e reportadas 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 faz 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 nos nossos servidores, então não há navegador, nem Chrome headless, nem biblioteca de mapas na sua stack. Uma única chamada HTTP retorna a imagem finalizada.