Pesquisar locais

A ferramenta search_places permite que um LLM encontre lugares no Google Maps usando uma consulta em linguagem natural. A ferramenta retorna um resumo gerado com IA dos lugares correspondentes. Para cada lugar citado, o resumo também retorna o ID de lugar, as coordenadas, os links do Google Maps e a atribuição.

Nesta página, descrevemos as opções de solicitação, incluindo as opções Pro, o que a resposta contém e como as solicitações são faturadas. Para ver o esquema completo da ferramenta, consulte a referência de search_places.

Opções de solicitação

O LLM define essas opções ao chamar a ferramenta, com base na solicitação do usuário e na descrição da ferramenta. É possível influenciar as opções que o modelo usa com suas próprias instruções. Consulte Controlar o uso do Pro.

Opção Descrição
text_query Obrigatório. A consulta de pesquisa, por exemplo, coffee shops near Golden Gate Park. A consulta precisa conter informações de localização suficientes para não ser ambígua, ou a solicitação precisa incluir location_bias.
location_bias Um círculo (center e radius_meters opcional, até 50.000 metros) para priorizar os resultados. Se text_query nomear um local explícito, esse local será usado.
language_code O idioma do resumo, por exemplo, en ou ja. O padrão é inglês.
region_code O código regional CLDR do usuário, por exemplo, US. Afeta nomes de lugares específicos de uma região e pode afetar os resultados com base na legislação aplicável.
page_size O número máximo de lugares a serem retornados. O padrão é 5. Os valores de 6 a 10 são uma opção Pro. Valores acima de 10 retornam um erro INVALID_ARGUMENT. O serviço pode retornar menos lugares do que o solicitado.
include_extended_details Quando true, o resumo inclui detalhes estendidos do lugar. Esta é uma opção Pro. O padrão é false.

Opções Pro

Duas opções selecionam a SKU Pro. Uma solicitação que usa um ou ambos é faturada com a SKU Pro:

Opção Pro Quando usar
include_extended_details teve o endereço definido como true A solicitação do usuário precisa de detalhes estendidos do lugar, como insights de avaliações, destaques do menu, atmosfera ou dicas de visitantes.
page_size de 6 a 10 O usuário quer comparar mais de cinco lugares.

As solicitações que não usam nenhuma das opções, incluindo aquelas com um page_size de 1 a 5, são faturadas de acordo com a SKU Essentials.

Detalhes estendidos do lugar

Defina include_extended_details como true quando a solicitação do usuário precisar de insights qualitativos, condições em tempo real ou atributos especializados, como:

  • O que os avaliadores dizem: insights baseados em avaliações, sentimento do cliente e feedback.
  • Ofertas específicas: itens do cardápio, pratos, especialidades, bebidas ou destaques da empresa.
  • Atmosfera: decoração interior, estética, ambiente ou clima.
  • Dicas práticas para visitantes: se é preciso reservar com antecedência, políticas de entrada sem reserva, tempos de espera, movimento do lugar, estacionamento e instalações.
  • Proximidade: distância ou tempo de viagem do local da consulta ou do centro de location_bias, quando o usuário pergunta o que está por perto ou mais próximo.

Os insights em um resumo dependem da consulta e dos dados disponíveis para cada lugar. Nem todos os tipos de insight aparecem em todas as respostas.

Deixe como false (o padrão) para pesquisas padrão: culinárias ou tipos de loja, endereços, informações de contato, horário de funcionamento e comodidades padrão. As solicitações com detalhes estendidos levam mais tempo para serem concluídas.

Os detalhes estendidos não mudam a estrutura da resposta. Sem eles, o resumo descreve cada lugar em uma ou duas frases. Com eles, cada lugar recebe uma descrição mais longa que se baseia em mais dados do Google Maps, incluindo insights de avaliações. As entradas estruturadas de places são as mesmas para as duas SKUs.

Exemplo

A solicitação a seguir pede até 8 lugares com detalhes estendidos. Ele é faturado na SKU 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
}

Sem detalhes estendidos, o resumo descreve cada lugar em uma ou duas frases:

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 · $$$) Um restaurante intimista à luz de velas que os avaliadores descrevem como romântico, mas barulhento nos fins de semana. Os pratos de destaque incluem o tagliatelle al ragù, a burrata e o tiramisu. Recomendamos fazer reservas. Clientes sem reserva podem esperar de 30 a 45 minutos nas noites de sexta-feira e sábado, e o estacionamento público é limitado.

Resposta

A resposta contém:

  • summary: um resumo em linguagem natural dos resultados da pesquisa. Ele pode conter citações baseadas em zero, como [0], que são mapeadas para entradas em places.
  • places[]: os lugares mencionados no resumo. Cada lugar inclui:
    • place: o nome do recurso do lugar, no formato places/{id}.
    • id: o ID de lugar. Você pode usá-lo com outras APIs da Plataforma Google Maps, por exemplo, para mostrar o lugar em um mapa.
    • location: a latitude e a longitude do lugar.
    • googleMapsLinks: links do Google Maps para o lugar (placeUrl), rotas (directionsUrl), avaliações (reviewsUrl), fotos (photosUrl) e para escrever uma avaliação (writeAReviewUrl).
    • attribution: a atribuição que você precisa mostrar com o lugar. Consulte os requisitos de atribuição.

A resposta tem a mesma estrutura para as duas SKUs. Para detalhes do campo, consulte a referência de search_places.

Opções do Pro durante a GA restrita

Durante a GA restrita, as opções Pro estão disponíveis apenas para projetos na lista de permissões Pro. Se o projeto ainda não estiver na lista de permissões, as opções do Pro serão ignoradas, em vez de rejeitadas:

  • include_extended_details é tratado como false.
  • Os valores de page_size acima de 5, incluindo valores acima de 10, são reduzidos para 5.

A solicitação é faturada de acordo com a SKU Essentials. Para solicitar acesso, consulte Opções Pro durante a GA restrita.

Faturamento e cotas

Cada solicitação search_places é um evento faturável:

A cota de search_places é de 300 consultas por minuto, por projeto, compartilhada por ambas as SKUs. Para preços, consulte a tabela de preços principal e a tabela de preços da Índia.