API Maps Tools Resolution

A API Maps Tools Resolution faz parte do Grounding Lite do Maps. Ele fornece endpoints em lote que resolvem nomes de locais e URLs do Google Maps para IDs de lugares 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:

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 projeto do Google Cloud.

Acesso e autenticação da API

A API Resolution é compatível com chaves de API e credenciais do OAuth 2.0.

Chave de API

É possível autenticar solicitações transmitindo uma chave de API válida da Plataforma Google Maps no cabeçalho X-Goog-Api-Key ou anexando-a ao 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ê usa a autorização OAuth, o seguinte escopo é compatível:

• 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 e 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, não importa quantos itens ela contenha.

Preços

As solicitações para ResolveNames e ResolveMapsUrls são faturadas sem custo financeiro (US$ 0) no SKU API Places: Text Search Fundamentos da Pesquisa (somente IDs). Assim como no restante do Maps 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 um máximo de 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 ou endereço específico (por exemplo, "Googleplex, Mountain View, CA" ou "Torre Eiffel, Paris").
  • Pesquisas categóricas gerais (por exemplo, "restaurantes em São Paulo") 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 do ResolveMapsUrls:
  • Cada URL precisa ser um URL do Google Maps estruturalmente válido.
  • Formatos compatíveis:
    • URL padrão do lugar: https://www.google.com/maps/place/...
    • URL abreviado: https://maps.app.goo.gl/...
  • URLs gerais do Maps baseados em consultas (por exemplo, https://maps.google.com/?q=restaurant) e URLs que não apontam para um único lugar exclusivo 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. Este é um único link do 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 crie o link por conta própria. Se nenhum item no lote for resolvido, a resposta não vai incluir saveToMapsUrl.

Processar erros parciais

Ambos os 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 a resposta para falhas por item.

Interpretar a resposta

1. Alinhamento garantido de 1:1: a lista results retornada (para ResolveNames) ou entities (para ResolveMapsUrls) mapeia 1:1 com a lista de entrada, por índice.
2. 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.
3. Mapa failedRequests: a resposta contém um mapa failedRequests.
   • A chave é o índice de base zero 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.
4. saveToMapsUrl abrange apenas sucessos: o link saveToMapsUrl inclui apenas os itens 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 saber 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:

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 de novo.

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 das ferramentas 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 construir um link por conta própria.

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 direcionar os resultados a uma região local.
• regionCode (opcional): código do 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 item é 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 como 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 público do Issue Tracker do Maps Grounding Lite:

• Informar um bug
• Enviar uma solicitação de recurso
• Enviar feedback