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 cita el resumen, también devuelve el ID de lugar, las coordenadas, los vínculos de Google Maps y la atribución.

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 obtener el esquema completo de la herramienta, consulta la referencia de search_places.

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.

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 Es el idioma del resumen, por ejemplo, en o ja. El valor predeterminado es inglés.
region_code Es el código de región 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 es 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 Pro. Una solicitud que use uno o ambos se facturará 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 es necesario reservar con anticipación, políticas de ingreso sin reserva, 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 búsqueda 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 ellas, 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

En la siguiente solicitud, se piden 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
}

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

Trattoria de ejemplo [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 lo siguiente:

  • 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: Es la latitud y la longitud del lugar.
    • googleMapsLinks: Son vínculos de Google Maps para el lugar (placeUrl), las instrucciones sobre cómo llegar (directionsUrl), las opiniones (reviewsUrl), las 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.

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

Opciones de Pro durante la DG restringida

Durante la fase de DG restringida, las opciones de Pro solo están disponibles para los proyectos que se encuentran en la lista de entidades permitidas de Pro. Si tu proyecto aún no está en la lista de entidades permitidas, las opciones de Pro se ignoran en lugar de rechazarse:

  • include_extended_details se trata como false.
  • Los valores de page_size superiores a 5, incluidos los superiores a 10, se reducen a 5.

La solicitud se factura con el SKU de Essentials. Para solicitar acceso, consulta Opciones de Pro durante la DG restringida.

Facturación y cuotas

Cada solicitud de search_places es un evento facturable:

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