API Maps Tools Resolution (experimental)

A API Maps Tools Resolution fornece endpoints de processamento em lote para resolver nomes de locais e URLs em IDs de lugares do Google Maps.

Acesso e autenticação da API

Métodos de autenticação

As APIs são compatíveis com credenciais de chave de API e OAuth 2.0:

1. Chave de API

É possível autenticar solicitações anexando uma chave de API válida da Plataforma Google Maps ao URL da solicitação ou no cabeçalho X-Goog-Api-Key:

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. Escopos do OAuth 2.0

Se você estiver usando a autorização OAuth, os seguintes escopos serão aceitos:

  • https://www.googleapis.com/auth/maps-platform.mapstools (recomendado)

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: as duas APIs permitem um máximo de 20 itens por solicitação.
  • Requisitos da API ResolveNames:
    • Cada item de consultas precisa especificar um parâmetro de texto não vazio.
    • As consultas precisam representar um nome ou endereço de lugar específico (por exemplo, "Googleplex, Mountain View, CA", "Torre Eiffel, Paris").
    • Pesquisas categóricas gerais (por exemplo, "restaurantes em Nova York") ou nomes de redes genéricos sem um local (por exemplo, "Starbucks") não são aceitas e podem falhar na resolução.
  • Requisitos da API ResolveMapsUrls:
    • Cada URL precisa ser um URL do Google Maps estruturalmente válido.
    • Os formatos aceitos incluem:
      • URL de lugar padrão: https://www.google.com/maps/place/...
      • URL encurtado: https://maps.app.goo.gl/...
    • URLs do Maps baseados em consultas gerais (por exemplo, https://maps.google.com/?q=restaurant) e URLs que não apontam para um único lugar exclusivo não são aceitos.

Como lidar com erros parciais

As duas APIs são projetadas como 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.

Como interpretar a resposta

  1. Alinhamento 1:1 garantido: os resultados retornados (para ResolveNames) ou as listas de entidades (para ResolveMapsUrls) são mapeadas 1:1 com a lista de entrada.
  2. Elementos vazios para falhas: se um 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 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 de erro específico (de status gRPC/HTTP padrão) e uma mensagem detalhada explicando o motivo da falha.

Falhas de nível superior

Um erro HTTP de nível superior (por exemplo, 400 Bad Request) é retornado apenas se a solicitação falhar na validação (por exemplo, ao transmitir mais de 20 itens ou campos obrigatórios ausentes).

Especificação da API e exemplos de curl

1. API ResolveNames

Método: POST

https://mapstools.googleapis.com/v1alpha: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 de país CLDR (por exemplo, "US", "FR") para direcionar 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/v1alpha:resolveNames?key=KEY"
Resposta JSON
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Exemplo de curl: resultados mistos (falha parcial)

Neste exemplo, o primeiro item é um texto lixo não resolúvel, 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/v1alpha:resolveNames?key=KEY"
Resposta JSON
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. API ResolveMapsUrls

Método: POST

https://mapstools.googleapis.com/v1alpha: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

Como resolver um link 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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
Resposta JSON
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Exemplo de curl: resultados mistos (falha parcial)

Como resolver um URL de lugar válido e um URL malformado/não aceito.

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
Resposta JSON
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Exemplo de curl: falha de validação

Como tentar transmitir 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/v1alpha:resolveMapsUrls?key=KEY"
Resposta JSON
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}