MCP Tools Reference: mapstools.googleapis.com

Ferramenta: search_places

Chame essa ferramenta quando a solicitação do usuário for encontrar lugares, empresas, endereços, locais, pontos de interesse ou qualquer outra pesquisa relacionada ao Google Maps.

Requisitos de entrada (CRÍTICO):

  1. text_query (string - OBRIGATÓRIO): a consulta de pesquisa principal. Isso precisa definir claramente o que o usuário está procurando.

    • Exemplos:'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
    • Para detalhes de um lugar específico:inclua o atributo solicitado (por exemplo, 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

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

    • Formato: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • Uso:
      • Para favorecer um raio de 5 km:{"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • Para favorecer fortemente o ponto central:{"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (omitindo radius_meters).

  3. language_code (string - OPCIONAL): o idioma em que o resumo dos resultados da pesquisa será mostrado.

    • Formato:um código de idioma de duas letras (ISO 639-1), opcionalmente seguido por um sublinhado e um código de país de duas letras (ISO 3166-1 alpha-2). Por exemplo, en, ja, en_US, zh_CN, es_MX. Se o código de idioma não for fornecido, os resultados serão em inglês.

  4. region_code (string - OPCIONAL): o código regional CLDR Unicode do usuário. Esse parâmetro é usado para mostrar os detalhes do lugar, como o nome específico da região, se disponível. O parâmetro pode afetar os resultados com base na legislação aplicável.

    • Formato:um código de país com duas letras (ISO 3166-1 alfa-2), por exemplo, US, CA.

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

  • Informações de local (CRÍTICO): a pesquisa precisa conter informações de local suficientes. Se o local for ambíguo (por exemplo, apenas "pizzarias"), você precisa especificar no text_query (por exemplo, "pizzarias em Nova York") ou use o parâmetro location_bias. Inclua o nome da cidade, do estado/província e da região/país, se necessário, para evitar ambiguidade.

  • Sempre forneça o text_query mais específico e contextual possível.

  • Use location_bias somente se as coordenadas forem fornecidas explicitamente ou se for apropriado e necessário inferir um local do contexto conhecido de um usuário para ter resultados melhores.

O exemplo a seguir demonstra como usar curl para invocar a ferramenta search_places 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": "search_places",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

Mensagem de solicitação para "SearchText".

SearchTextRequest

Representação JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "pageToken": string,

  // Union field _location_bias can be only one of the following:
  "locationBias": {
    object (LocationBias)
  }
  // End of list of possible types for union field _location_bias.
}
Campos
textQuery

string

Obrigatório. A consulta de texto.
languageCode

string

Opcional. O idioma em que o resumo será retornado. Se o código de idioma não for especificado ou não for reconhecido, o resumo com preferência por inglês será retornado.

Por exemplo, "en" para inglês.

Lista atual de idiomas disponíveis: https://developers.google.com/maps/faq#languagesupport.
regionCode

string

Opcional. O código de país/região Unicode (CLDR) do local de origem da solicitação. Esse parâmetro é usado para mostrar os detalhes do lugar, como o nome específico da região, se disponível. O parâmetro pode afetar os resultados com base na legislação aplicável.

Por exemplo, "US" para Estados Unidos.

Para mais informações, consulte https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.

No momento, não há suporte para códigos de região de três dígitos.
pageSize

integer

Opcional. O número máximo de lugares a serem retornados. O serviço pode retornar um valor inferior a este.
pageToken

string

Opcional. Um token de página recebido de uma chamada SearchText anterior. Forneça isso para recuperar a página subsequente.

Campo de união _location_bias.

_location_bias pode ser apenas de um dos tipos a seguir:
locationBias

object (LocationBias)

Uma região opcional para direcionar os resultados da pesquisa. Se um local explícito estiver em text_query, ele será usado para influenciar os resultados da pesquisa em vez desse campo.

LocationBias

Representação JSON 
{
  "circle": {
    object (Circle)
  }
}
Campos
circle

object (Circle)

Opcional. Um círculo definido por um ponto central e um raio. O radius_meters é opcional. Se não for definido, os resultados serão tendenciosos em relação ao ponto central.

Círculo

Representação JSON 
{
  "center": {
    object (google.type.LatLng)
  },

  // Union field _radius_meters can be only one of the following:
  "radiusMeters": number
  // End of list of possible types for union field _radius_meters.
}
Campos
center

object (google.type.LatLng)

Obrigatório. O ponto central do círculo.

Campo de união _radius_meters.

_radius_meters pode ser apenas de um dos tipos a seguir:
radiusMeters

number

O raio do círculo em metros. O raio precisa estar dentro de 50.000 metros.

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 SearchText.

SearchTextResponse

Representação JSON 
{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string,
  "nextPageToken": string
}
Campos
places[]

object (PlaceView)

Apenas saída. A lista de lugares mencionados no resumo.
summary

string

Apenas saída. Um resumo em linguagem natural dos resultados da pesquisa. O resumo pode conter citações baseadas em zero, como "[0]", "[1]", "[2]" etc. Essas citações são mapeadas para os lugares correspondentes no campo places.
nextPageToken

string

Opcional. Um token que pode ser enviado como page_token para recuperar a próxima página.

PlaceView

Representação JSON 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (google.type.LatLng)
  }
  // End of list of possible types for union field _location.
}
Campos
place

string

O nome do recurso do lugar subjacente, no formato "places/{id}".
id

string

O ID do lugar subjacente.
googleMapsLinks

object (GoogleMapsLinks)

Links para acionar diferentes ações do Google Maps.

Campo de união _location.

_location pode ser apenas de um dos tipos a seguir:
location

object (google.type.LatLng)

A posição deste lugar.

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].
Representação JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
Campos
directionsUrl

string

Um link para mostrar as rotas até o local. O link só preenche o local de destino e usa o modo de viagem padrão DRIVE.
placeUrl

string

Um link para mostrar este lugar.
writeAReviewUrl

string

Um link para escrever uma avaliação deste lugar no Google Maps.
reviewsUrl

string

Um link para mostrar as avaliações desse lugar no Google Maps.
photosUrl

string

Um link para mostrar as avaliações desse lugar no Google Maps.

Anotações de ferramentas

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