Buscar lugares

La herramienta search_places permite que un LLM encuentre lugares en Google Maps a partir de una consulta en lenguaje natural. La herramienta devuelve un resumen generado por IA de los lugares que coinciden. Para cada lugar que se cita en el resumen, también se devuelven el ID de lugar, las coordenadas de latitud y longitud, los vínculos de Google Maps y la atribución.

Puedes llamar a search_places a través del servidor de MCP o como el método REST searchText. En esta página, se describen las opciones de solicitud, incluidas las opciones de Pro, lo que contiene la respuesta y cómo se facturan las solicitudes. Para ver los esquemas completos, consulta la referencia de MCP de search_places y la referencia de REST de searchText.

Opciones de solicitud

El LLM establece estas opciones cuando llama a la herramienta, según la solicitud del usuario y la descripción de la herramienta. Puedes influir en las opciones que usa el modelo con tus propias instrucciones. Consulta Controla el uso de Pro.

En la siguiente tabla, se describen las opciones de solicitud para search_places:

Opción Descripción
text_query Obligatorio. La búsqueda, por ejemplo, coffee shops near Golden Gate Park. La consulta debe contener suficiente información de ubicación para que no sea ambigua, o bien la solicitud debe incluir location_bias.
location_bias Un círculo (center y radius_meters opcional, de hasta 50,000 metros) para personalizar los resultados Si text_query nombra una ubicación explícita, se usa esa ubicación en su lugar.
language_code El idioma del resumen, por ejemplo, en o ja. El valor predeterminado es inglés.
region_code Es el código regional de CLDR del usuario, por ejemplo, US. Afecta los nombres de lugares específicos de la región y puede afectar los resultados según la ley aplicable.
page_size Es la cantidad máxima de lugares que se devolverán. El valor predeterminado es 5. Los valores del 6 al 10 son una opción Pro. Los valores superiores a 10 devuelven un error INVALID_ARGUMENT. Es posible que el servicio devuelva menos lugares de los solicitados.
include_extended_details Cuando se establece en true, el resumen incluye detalles extendidos del lugar. Esta es una opción Pro. La configuración predeterminada es false.

Opciones de Pro

Dos opciones seleccionan el SKU de Maps Grounding Pro. Una solicitud que use uno o ambos se factura con el SKU Pro:

Opción Pro Cuándo se utiliza
Se estableció true como la dirección de tu include_extended_details La solicitud del usuario necesita detalles extendidos del lugar, como estadísticas de opiniones, aspectos destacados del menú, ambiente o sugerencias de los visitantes.
page_size de 6 a 10 El usuario quiere comparar más de 5 lugares.

Las solicitudes que no usan ninguna de las opciones, incluidas las solicitudes con un page_size de 1 a 5, se facturan con el SKU de Essentials.

Detalles extendidos del lugar

Establece include_extended_details en true cuando la solicitud del usuario necesite información cualitativa, condiciones en tiempo real o atributos especializados, como los siguientes:

  • Qué dicen los usuarios: estadísticas basadas en opiniones, opiniones de los clientes y comentarios.
  • Ofertas específicas: elementos del menú, platos, especialidades de comida, bebidas o aspectos destacados de la empresa.
  • Atmósfera: decoración interior, estética, ambiente o estado de ánimo
  • Sugerencias prácticas para los visitantes: si se debe reservar con anticipación, políticas de ingreso sin cita previa, tiempos de espera, qué tan concurrido está el lugar, estacionamiento e instalaciones.
  • Proximidad: Es la distancia o la duración del viaje desde la ubicación de la consulta o el centro de location_bias cuando el usuario pregunta qué hay cerca o qué es lo más cercano.

Las estadísticas de un resumen dependen de la consulta y de los datos disponibles para cada lugar. No todos los tipos de estadísticas aparecen en todas las respuestas.

Déjalo como false (el valor predeterminado) para las búsquedas estándar: tipos de cocina o de tienda, direcciones, información de contacto, horario de atención y comodidades estándar. Las solicitudes con detalles extendidos tardan más en completarse.

Los detalles extendidos no cambian la estructura de la respuesta. Sin ellos, el resumen describe cada lugar en una o dos oraciones. Con ellos, cada lugar obtiene una descripción más larga que se basa en más datos de Google Maps, incluidas las estadísticas de las opiniones. Las entradas estructuradas de places son las mismas para ambos SKU.

Ejemplo

La siguiente solicitud de MCP pide hasta 8 lugares con detalles extendidos. Se factura con el SKU de Pro:

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

En el siguiente ejemplo, se envía la misma solicitud al método REST searchText:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

Reemplaza API_KEY por tu clave de API.

Sin detalles extendidos, el resumen describe cada lugar en una o dos oraciones:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) Un comedor íntimo iluminado con velas que los usuarios describen como romántico, pero ruidoso los fines de semana. Entre los platos destacados, se encuentran los tagliatelle al ragù, la burrata y el tiramisú. Se recomienda hacer reservas; los clientes sin reserva pueden esperar entre 30 y 45 minutos los viernes y sábados por la noche, y el estacionamiento en la calle es limitado.

Respuesta

La respuesta contiene los siguientes campos:

  • summary: Es un resumen en lenguaje natural de los resultados de la búsqueda. Puede contener citas basadas en cero, como [0], que se asignan a entradas en places.
  • places[]: Son los lugares que se mencionan en el resumen. Cada lugar incluye lo siguiente:
    • place: Es el nombre del recurso del lugar, con el formato places/{id}.
    • id: Es el ID de lugar. Puedes usarlo con otras APIs de Google Maps Platform, por ejemplo, para mostrar el lugar en un mapa.
    • location: Son las coordenadas de latitud y longitud del lugar.
    • googleMapsLinks: Son vínculos de Google Maps para el lugar (placeUrl), instrucciones sobre cómo llegar (directionsUrl), opiniones (reviewsUrl), fotos (photosUrl) y la opción para escribir una opinión (writeAReviewUrl).
    • attribution: Es la atribución que debes mostrar con el lugar. Consulta los requisitos de atribución.
  • contentToken: Es un token de visualización de datos de agentes (versión preliminar) que te permite mostrar los lugares de la respuesta con el kit de IU de Places sin costo adicional. Se devuelve cuando la respuesta incluye al menos un lugar.

La respuesta tiene la misma estructura para ambos SKU, y para MCP y REST. Para obtener detalles de los campos, consulta la referencia de search_places.

Facturación y cuotas

Cada solicitud de search_places es un evento facturable:

Si muestras los lugares de una respuesta de search_places con el kit de IU de Places, puedes usar el token de visualización de datos de agentes (versión preliminar) para que no se facturen esas solicitudes del kit de IU de Places.

La cuota de search_places es de 300 consultas por minuto para cada proyecto, que comparten ambos SKU. Para conocer los precios, consulta la tabla de precios principal y la tabla de precios de India.