O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

API Maps Tools Resolution

A API Maps Tools Resolution faz parte do Maps Grounding Lite. Ela fornece endpoints em lote que resolvem nomes de locais e URLs do Google Maps para IDs de lugar do Google Maps. Você pode usar os IDs de lugar retornados com outras APIs da Plataforma Google Maps. Cada resposta também inclui um link que salva os lugares resolvidos como uma lista no Google Maps.

A API Resolution está disponível como métodos REST e como ferramentas no servidor MCP do Maps Grounding Lite:

Capacidade	Método REST	Ferramenta MCP
Resolver nomes ou endereços de locais para lugares	`resolveNames`	`resolve_names`
Resolver URLs do Google Maps para lugares	`resolveMapsUrls`	`resolve_maps_urls`

Antes de começar

Para usar a API Resolution, você precisa de um projeto na nuvem do Google Cloud com o faturamento ativado e o serviço da API Maps Grounding Lite ativado. Para instruções, consulte Ativar o serviço Maps Grounding Lite no seu projeto do Google Cloud.

Acesso e autenticação de APIs

A API Resolution aceita credenciais de chave de API e OAuth 2.0.

Chave de API

Para autenticar solicitações, transmita uma chave de API válida da Plataforma Google Maps no cabeçalho X-Goog-Api-Key ou adicione-a ao final do URL da solicitação:

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

Nos exemplos desta página, substitua API_KEY pela sua chave de API.

Escopos do OAuth 2.0

Se você usar a autorização OAuth, o seguinte escopo será aceito:

https://www.googleapis.com/auth/maps-platform.mapstools

Limites de uso

As seguintes cotas padrão se aplicam à API Resolution:

ResolveNames: 600 consultas por minuto, por projeto.
ResolveMapsUrls: 600 consultas por minuto, por projeto.
Tamanho do lote: até 20 consultas ou URLs por solicitação.

Cada solicitação conta como uma consulta, independentemente de quantos itens ela contém.

Preços

As solicitações para ResolveNames e ResolveMapsUrls são faturadas sem custo financeiro (US$ 0) na SKU API Places: Text Search Essentials (somente IDs). Assim como no restante do Grounding Lite, seu projeto precisa ter uma conta de faturamento.

Validação e restrições de solicitações

Para evitar carga excessiva e garantir tempos de resposta rápidos, as solicitações em lote são validadas de forma rigorosa:

Limite de tamanho do lote: os dois métodos permitem no máximo 20 itens por solicitação.
Requisitos do ResolveNames:
- Cada item em queries precisa especificar um parâmetro text não vazio.
- As consultas precisam representar um nome de lugar ou endereço específico (por exemplo, "Googleplex, Mountain View, CA" ou "Torre Eiffel, Paris").
- Pesquisas categóricas gerais (por exemplo, "restaurantes em Nova York") ou nomes de redes genéricas sem um local (por exemplo, "Starbucks") não são compatíveis e podem não ser resolvidas.
Requisitos de ResolveMapsUrls:
- Cada URL precisa ser um URL do Google Maps estruturalmente válido.
- Os formatos compatíveis incluem:
  - URL de lugar padrão: https://www.google.com/maps/place/...
  - URL encurtado: https://maps.app.goo.gl/...
- URLs gerais do Maps baseados em consulta (por exemplo, https://maps.google.com/?q=restaurant) e URLs que não apontam para um único lugar não são aceitos.

Salvar lugares resolvidos no Google Maps

Se pelo menos um item em um lote for resolvido, a resposta vai incluir um campo saveToMapsUrl. É um único link do Google Maps que contém todos os lugares resolvidos com sucesso no lote. Apresente esse link aos usuários que querem salvar, compartilhar ou abrir os lugares resolvidos como uma lista no Google Maps.

Sempre use o link retornado pela API. Não construa o link por conta própria. Se nenhum item no lote for resolvido, a resposta não vai incluir saveToMapsUrl.

Tratar erros parciais

Os dois métodos são processadores em lote. Se alguns itens em um lote não forem resolvidos, a solicitação geral não vai falhar com um erro de nível superior. Em vez disso, a API retorna uma resposta de sucesso parcial, e você precisa verificar se há falhas por item.

Interpretar a resposta

Alinhamento 1:1 garantido: a lista results (para ResolveNames) ou entities (para ResolveMapsUrls) retornada é mapeada 1:1 com a lista de entrada, por índice.
Elementos vazios para falhas: se o item no índice i não for resolvido, a lista de resultados vai conter um objeto vazio {} no índice i.
Mapa failedRequests: a resposta contém um mapa failedRequests.
- A chave é o índice baseado em 0 do item com falha (representado como uma string em JSON).
- O valor é um objeto google.rpc.Status que contém o código do erro e uma mensagem explicando por que o item falhou.
saveToMapsUrl abrange apenas os sucessos: o link saveToMapsUrl inclui apenas os itens que foram resolvidos. Os itens com falha não são incluídos.

Não presuma que todo o lote falhou porque um item falhou. Sempre verifique failedRequests para descobrir quais itens, se houver, não puderam ser resolvidos.

Erros por item

A tabela a seguir lista os erros por item que podem aparecer em failedRequests:

Método	Causa	Código	Mensagem
`ResolveNames`	Não é possível resolver o nome ou endereço para um lugar.	`5` (`NOT_FOUND`)	`Place not found.`
`ResolveMapsUrls`	Não é possível resolver o URL para um lugar.	`3` (`INVALID_ARGUMENT`)	`Failed to resolve Maps URL to a place.`
Ambos os métodos	Ocorreu um erro interno ao resolver o item.	`13` (`INTERNAL`)	`Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support`

Tente novamente apenas os itens que falharam com INTERNAL.

Falhas de nível superior

A API retorna um erro de nível superior em vez de uma resposta parcial nos seguintes casos:

Solicitação inválida (400 INVALID_ARGUMENT): a solicitação contém mais de 20 itens, uma solicitação ResolveNames não tem consultas ou tem uma consulta com um valor text vazio, ou uma solicitação ResolveMapsUrls tem um URL vazio ou que não é sintaticamente válido. Um item inválido faz com que toda a solicitação falhe.
Erros de autenticação, permissão ou cota: por exemplo, a chave de API está ausente ou é inválida, ou a solicitação excede os limites de uso.
Erros de servidor (500 INTERNAL): tente fazer a solicitação novamente.

Usar a API Resolution com o MCP

O servidor MCP do Maps Grounding Lite em https://mapstools.googleapis.com/mcp expõe a API Resolution como duas ferramentas:

resolve_names: resolve um lote de nomes ou endereços de locais para IDs de lugar.
resolve_maps_urls: resolve um lote de URLs do Google Maps para IDs de lugar.

Quando você configura seu LLM para usar o servidor MCP do Maps Grounding Lite, essas ferramentas ficam disponíveis junto com as outras ferramentas do Maps Grounding Lite. As ferramentas aceitam as mesmas entradas, aplicam as mesmas restrições e retornam a mesma resposta de falha parcial que os métodos REST.

As respostas da ferramenta incluem o campo save_to_maps_url. As descrições da ferramenta instruem o LLM a apresentar esse link quando o usuário quiser salvar, compartilhar ou abrir os lugares resolvidos como uma lista no Google Maps, em vez de criar um link.

O exemplo a seguir usa curl para chamar a ferramenta resolve_names diretamente:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Para chamar resolve_maps_urls, defina name como resolve_maps_urls e transmita uma matriz urls em arguments.

Especificação da API REST e exemplos de curl

ResolveNames

Método: POST

https://mapstools.googleapis.com/v1:resolveNames

Formato do corpo da solicitação

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

queries (obrigatório): lista repetida de consultas a serem resolvidas (máximo de 20).
locationBias (opcional): caixa delimitadora da janela de visualização para priorizar resultados de uma região local.
regionCode (opcional): código de país CLDR (por exemplo, "US" ou "FR") para influenciar os resultados.

Exemplo de curl: resolução bem-sucedida

Essa consulta resolve "Googleplex" e "Torre Eiffel".

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

Resposta JSON

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Exemplo de curl: resultados mistos (falha parcial)

Neste exemplo, o primeiro item é um texto que não pode ser resolvido, e o segundo é um lugar válido.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

Resposta JSON

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

Método: POST

https://mapstools.googleapis.com/v1:resolveMapsUrls

Formato do corpo da solicitação

{
  "urls": [
    "string"
  ]
}

urls (obrigatório): lista repetida de strings de URL do Google Maps a serem resolvidas (máximo de 20).

Exemplo de curl: resolução bem-sucedida

O exemplo a seguir resolve um URL de lugar padrão do Google Maps:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

Resposta JSON

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Exemplo de curl: resultados mistos (falha parcial)

O exemplo a seguir resolve um URL de lugar válido e um URL que não pode ser resolvido para um lugar:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

Resposta JSON

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Exemplo de curl: falha na validação

O exemplo a seguir transmite mais de 20 URLs em uma única solicitação:

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

Resposta JSON

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

Enviar feedback

Para informar um problema ou compartilhar feedback sobre a API Resolution, use o componente do Issue Tracker público do Maps Grounding Lite:

API Maps Tools Resolution Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Acesso e autenticação de APIs

Chave de API

Escopos do OAuth 2.0

Limites de uso

Preços

Validação e restrições de solicitações

Salvar lugares resolvidos no Google Maps

Tratar erros parciais

Interpretar a resposta

Erros por item

Falhas de nível superior

Usar a API Resolution com o MCP

Especificação da API REST e exemplos de curl

ResolveNames

Método: POST

Formato do corpo da solicitação

Exemplo de curl: resolução bem-sucedida

Resposta JSON

Exemplo de curl: resultados mistos (falha parcial)

Resposta JSON

ResolveMapsUrls

Método: POST

Formato do corpo da solicitação

Exemplo de curl: resolução bem-sucedida

Resposta JSON

Exemplo de curl: resultados mistos (falha parcial)

Resposta JSON

Exemplo de curl: falha na validação

Resposta JSON

Enviar feedback

API Maps Tools Resolution