MCP Tools Reference: mapstools.googleapis.com

Ferramenta: resolve_names

Resolve uma lista em lote de consultas de local específicas (nomes de pontos de referência ou endereços exatos) em IDs de lugar canônicos do Google Maps.

Requisitos de entrada (CRÍTICO):

  1. queries (matriz de objetos - OBRIGATÓRIO): uma lista de consultas de localizações a serem resolvidas. É possível especificar até 20 consultas.

    • Cada objeto de consulta precisa ter:
      • text (string - OBRIGATÓRIO): a consulta de texto que representa um nome de lugar ou endereço específico a ser resolvido.
        • Exemplos:'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (objeto - OPCIONAL): use para priorizar resultados próximos a uma área geográfica específica.

    • Formato:{"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (string - OPCIONAL): o código regional Unicode CLDR (código de país de duas letras, por exemplo, US, CA) do usuário para influenciar os resultados.

Instruções para chamada de função:

  • Especificidade (CRÍTICA): as consultas precisam representar um nome ou endereço de lugar específico. Pesquisas gerais, como 'restaurants', ou nomes de redes, como 'Starbucks', não são aceitas.
  • NÃO chame essa ferramenta se as ferramentas downstream que você planeja invocar já aceitarem strings de endereço ou nome de lugar diretamente.

Tratamento de erros (CRÍTICO):

  • Essa é uma ferramenta de processamento em lote. Uma solicitação pode retornar "resultados mistos" (por exemplo, algumas consultas são resolvidas com êxito, enquanto outras falham).
  • A lista de saída de results tem garantia de mapeamento 1:1 com os índices de entrada queries. Uma consulta com falha vai resultar em uma mensagem Result vazia (nenhum entity definido) no índice correspondente na lista results.
  • Você PRECISA verificar o campo de mapa failed_requests na resposta para identificar qual índice de consulta específico falhou. A chave de failed_requests representa o índice com base em zero da consulta com falha na solicitação. Não presuma que toda a chamada em lote falhou devido a uma falha parcial.

O exemplo a seguir demonstra como usar curl para invocar a ferramenta resolve_names do MCP.

Solicitação curl 
                  
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

Mensagem de solicitação para ResolveNames.

ResolveNamesRequest

Representação JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Campos
queries[]

object (LocationQuery)

Obrigatório. Uma lista de consultas de local a serem resolvidas. É possível especificar até 20 consultas.
locationBias

object (LocationBias)

Opcional. Uma região opcional para influenciar os resultados da resolução. Se especificado, os resultados da resolução serão tendenciosos em relação às entidades mais próximas dessa região. Incluir location_bias ou region_code geralmente oferece resultados melhores ao restringir o espaço de pesquisa.

Se location_bias e region_code forem especificados, location_bias terá precedência sobre region_code.
regionCode

string

Opcional. Um código regional opcional para influenciar os resultados da resolução. Se especificado, os resultados da resolução serão tendenciosos em relação às entidades que estão na região especificada ou perto dela. Precisa ser um código de região CLDR. Por exemplo, "US" ou "CA". Incluir location_bias ou region_code geralmente oferece resultados melhores ao restringir o espaço de pesquisa.

Se location_bias e region_code forem especificados, location_bias terá precedência sobre region_code.

LocationQuery

Representação JSON 
{
  "text": string
}
Campos
text

string

Obrigatório. A consulta de texto para resolver uma entidade geoespacial específica no Google Maps, como um lugar ou um endereço. Quanto mais específica for a consulta, mais precisa será a resolução. Por exemplo, "São Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA" ou "Torre Eiffel, Paris". As consultas precisam ser um endereço ou nome de lugar específico. Locais gerais, como o nome de uma rede (por exemplo, Starbucks) ou uma consulta de pesquisa como "restaurantes", não são aceitos.

LocationBias

Representação JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Campos
Campo de união type. O tipo de viés de local. type pode ser apenas de um dos tipos a seguir:
viewport

object (Viewport)

Uma janela de visualização definida por uma caixa delimitadora.

Janela de visualização

Representação JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Campos
low

object (LatLng)

Obrigatório. O ponto baixo da janela de visualização.
high

object (LatLng)

Obrigatório. O ponto alto da janela de visualização.

LatLng

Representação JSON 
{
  "latitude": number,
  "longitude": number
}
Campos
latitude

number

A latitude em graus. Precisa estar no intervalo [-90,0, +90,0].
longitude

number

A longitude em graus. Precisa estar no intervalo [-180,0, +180,0].

Esquema de saída

Mensagem de resposta para ResolveNames.

ResolveNamesResponse

Representação JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
Campos
results[]

object (Result)

Apenas saída. A lista de entidades resolvidas das consultas de local. Garantia de mapeamento 1:1 com os índices queries da solicitação. Uma string vazia no índice i indica que a resolução falhou para essa consulta. Se a resolução falhar, verifique o campo failed_requests para conferir o status do erro.
failedRequests

map (key: integer, value: object (Status))

Apenas saída. Um mapa que comunica falhas parciais. A chave é o índice da solicitação com falha no campo queries. O valor é o status do erro que detalha por que a resolução falhou.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Resultado

Representação JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Campos
entity

object (Entity)

Apenas saída. A entidade resolvida da consulta de local.
confidence

enum (Confidence)

Apenas saída. O nível de confiança da resolução.

Entidade

Representação JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Campos
Campo de união entity. O tipo de entidade resolvido. entity pode ser apenas de um dos tipos a seguir:
place

string

O nome do recurso do lugar resolvido.

FailedRequestsEntry

Representação JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Campos
key

integer
value

object (Status)

Status

Representação JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campos
code

integer

O código de status, que precisa ser um valor de enumeração de google.rpc.Code.
message

string

Uma mensagem de erro em inglês para o desenvolvedor. Qualquer mensagem de erro para o usuário precisa ser localizada e enviada no campo google.rpc.Status.details, ou localizada pelo cliente.
details[]

object

Uma lista de mensagens com os detalhes do erro. Há um conjunto comum de tipos de mensagens para as APIs usarem.

Um objeto contendo campos de um tipo arbitrário. Um campo adicional "@type" contém uma URI que identifica o tipo. Exemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.

Qualquer

Representação JSON 
{
  "typeUrl": string,
  "value": string
}
Campos
typeUrl

string

Identifica o tipo da mensagem Protobuf serializada com uma referência de URI que consiste em um prefixo que termina em uma barra e o nome de tipo totalmente qualificado.

Exemplo: type.googleapis.com/google.protobuf.StringValue

Essa string precisa conter pelo menos um caractere /, e o conteúdo após o último / precisa ser o nome totalmente qualificado do tipo na forma canônica, sem um ponto inicial. Não escreva um esquema nessas referências de URI para que os clientes não tentem entrar em contato com elas.

O prefixo é arbitrário, e as implementações do Protobuf devem remover tudo até o último /, inclusive, para identificar o tipo. type.googleapis.com/ é um prefixo padrão comum exigido por algumas implementações legadas. Esse prefixo não indica a origem do tipo, e não é esperado que os URIs que o contêm respondam a solicitações.

Todas as strings de URL de tipo precisam ser referências de URI válidas com a restrição adicional (para o formato de texto) de que o conteúdo da referência deve consistir apenas em caracteres alfanuméricos, escapes codificados por porcentagem e caracteres no seguinte conjunto (sem incluir as crases externas): /-.~_!$&()*+,;=. Embora permitamos codificações de porcentagem, as implementações não devem remover o escape delas para evitar confusão com analisadores atuais. Por exemplo, type.googleapis.com%2FFoo deve ser rejeitado.

No design original do Any, foi considerada a possibilidade de iniciar um serviço de resolução de tipos nesses URLs, mas o Protobuf nunca implementou um e considera o contato com esses URLs problemático e um possível problema de segurança. Não tente entrar em contato com URLs de tipo.
value

string (bytes format)

Contém uma serialização Protobuf do tipo descrito por type_url.

Uma string codificada em base64.

Confiança

O nível de confiança da resolução.

Tipos enumerados
CONFIDENCE_UNSPECIFIED Valor padrão. Esse valor não é usado.
MEDIUM A confiança média indica que a resolução provavelmente está correta, mas pode haver outros candidatos.
HIGH Um alto nível de confiança indica que a resolução está correta e representa uma entidade geoespacial específica (por exemplo, um lugar específico).

Anotações de ferramentas

Dica destrutiva: ❌ | Dica idempotente: ❌ | Dica somente leitura: ✅ | Dica de mundo aberto: ❌