MCP Tools Reference: mapstools.googleapis.com

Herramienta: search_places

Llama a esta herramienta cuando la solicitud del usuario sea encontrar lugares, empresas, direcciones, ubicaciones, puntos de interés o cualquier otra búsqueda relacionada con Google Maps.

Requisitos de entrada (CRÍTICOS):

  1. text_query (cadena - OBLIGATORIO): Es la búsqueda principal. Debe definir claramente lo que busca el usuario.

    • Ejemplos: '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' y 'accessible public libraries in Los Angeles'.
    • Para obtener detalles de un lugar específico: Incluye el atributo solicitado (p.ej., 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

  2. location_bias (objeto; OPCIONAL): Usa este parámetro para priorizar los resultados cerca de un área geográfica específica.

    • Formato: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • Uso:
      • Para sesgar los resultados hacia un radio de 5 km, haz lo siguiente: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • Para sesgar fuertemente hacia el punto central: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (se omite radius_meters).

  3. language_code (cadena - OPCIONAL): Es el idioma en el que se mostrará el resumen de los resultados de la búsqueda.

    • Formato: Un código de idioma de dos letras (ISO 639-1), seguido de forma opcional por un guion bajo y un código de país de dos letras (ISO 3166-1 alpha-2), p.ej., en, ja, en_US, zh_CN, es_MX. Si no se proporciona el código de idioma, los resultados se mostrarán en inglés.

  4. region_code (cadena - OPCIONAL): Es el código regional CLDR de Unicode del usuario. Este parámetro se usa para mostrar los detalles del lugar, como el nombre específico de la región, si está disponible. El parámetro puede afectar los resultados según la legislación aplicable.

    • Formato: Código de país de dos letras (ISO 3166-1 alpha-2), p.ej., US, CA.

Instrucciones para la llamada a la herramienta:

  • Información de ubicación (CRÍTICA): La búsqueda debe contener suficiente información de ubicación. Si la ubicación es ambigua (p.ej., solo "pizzerías"), debes especificarla en text_query (p.ej., "pizzerías en Nueva York") o usa el parámetro location_bias. Incluye el nombre de la ciudad, el estado o la provincia, y la región o el país si es necesario para evitar ambigüedades.

  • Siempre proporciona el text_query más específico y enriquecido contextualmente posible.

  • Solo usa location_bias si se proporcionan coordenadas de forma explícita o si es adecuado y necesario inferir una ubicación a partir del contexto conocido de un usuario para obtener mejores resultados.

En el siguiente ejemplo, se muestra cómo usar curl para invocar la herramienta de MCP search_places.

Solicitud de 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

Es el mensaje de solicitud para SearchText.

SearchTextRequest

Representación 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

Obligatorio. Es la búsqueda de texto.
languageCode

string

Opcional. Es el idioma en el que se solicita que se devuelva el resumen. Si el código de idioma no se especifica o no se reconoce, se devolverá el resumen con una preferencia por el inglés.

Por ejemplo, "en" para inglés.

Lista actual de idiomas admitidos: https://developers.google.com/maps/faq#languagesupport.
regionCode

string

Opcional. Es el código Unicode de país o región (CLDR) de la ubicación desde la que se envía la solicitud. Este parámetro se usa para mostrar los detalles del lugar, como el nombre específico de la región, si está disponible. El parámetro puede afectar los resultados según la legislación aplicable.

Por ejemplo, “US” para Estados Unidos.

Para obtener más información, consulta https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.

Ten en cuenta que, por el momento, no se admiten los códigos de región de 3 dígitos.
pageSize

integer

Opcional. Es la cantidad máxima de lugares que se devolverán. El servicio puede mostrar menos que este valor.
pageToken

string

Opcional. Un token de página, recibido desde una llamada SearchText anterior. Proporciona esto para recuperar la página siguiente.

Campo de unión _location_bias.

_location_bias puede ser una de las siguientes opciones:
locationBias

object (LocationBias)

Es una región opcional para sesgar los resultados de la búsqueda. Si hay una ubicación explícita en text_query, se usará para sesgar los resultados de la búsqueda en lugar de este campo.

LocationBias

Representación JSON 
{
  "circle": {
    object (Circle)
  }
}
Campos
circle

object (Circle)

Opcional. Es un círculo definido por un punto central y un radio. El radius_meters es opcional. Si no se establece, los resultados se sesgarán hacia el punto central.

Círculo

Representación 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)

Obligatorio. Es el punto central del círculo.

Campo de unión _radius_meters.

_radius_meters puede ser una de las siguientes opciones:
radiusMeters

number

Radio del círculo en metros. El radio debe ser de hasta 50,000 metros.

LatLng

Representación JSON 
{
  "latitude": number,
  "longitude": number
}
Campos
latitude

number

La latitud expresada en grados. Debe pertenecer al rango [-90.0, +90.0].
longitude

number

La longitud expresada en grados. Debe pertenecer al rango [-180.0, +180.0].

Esquema de salida

Es el mensaje de respuesta para SearchText.

SearchTextResponse

Representación JSON 
{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string,
  "nextPageToken": string
}
Campos
places[]

object (PlaceView)

Solo salida. Es la lista de lugares que se mencionan en el resumen.
summary

string

Solo salida. Es un resumen en lenguaje natural de los resultados de la búsqueda. El resumen puede contener citas basadas en cero, como "[0]", "[1]", "[2]", etcétera. Estas citas se asignan a los lugares correspondientes en el campo places.
nextPageToken

string

Opcional. Es un token que se puede enviar como page_token para recuperar la página siguiente.

PlaceView

Representación 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

Nombre del recurso del lugar subyacente, con el formato "places/{id}".
id

string

Es el ID de lugar del lugar subyacente.
googleMapsLinks

object (GoogleMapsLinks)

Son vínculos para activar diferentes acciones de Google Maps.

Campo de unión _location.

_location puede ser una de las siguientes opciones:
location

object (google.type.LatLng)

Es la posición de este lugar.

LatLng

Representación JSON 
{
  "latitude": number,
  "longitude": number
}
Campos
latitude

number

La latitud expresada en grados. Debe pertenecer al rango [-90.0, +90.0].
longitude

number

La longitud expresada en grados. Debe pertenecer al rango [-180.0, +180.0].
Representación JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
Campos
directionsUrl

string

Es un vínculo para mostrar las instrucciones sobre cómo llegar al lugar. El vínculo solo completa la ubicación de destino y usa el modo de viaje predeterminado DRIVE.
placeUrl

string

Es un vínculo para mostrar este lugar.
writeAReviewUrl

string

Es un vínculo para escribir una opinión sobre este lugar en Google Maps.
reviewsUrl

string

Es un vínculo para mostrar las opiniones sobre este lugar en Google Maps.
photosUrl

string

Es un vínculo para mostrar las opiniones sobre este lugar en Google Maps.

Anotaciones de herramientas

Sugerencia destructiva: ❌ | Sugerencia idempotente: ❌ | Sugerencia de solo lectura: ✅ | Sugerencia de mundo abierto: ❌