Migrar para o novo Place Search

Esta página explica as diferenças entre os recursos de pesquisa de lugares com base em texto na classe Place (nova) e PlacesService (legado) e fornece alguns snippets de código para comparação.

O PlacesService legado tem os seguintes métodos de pesquisa com base em texto:

  • O método findPlaceFromQuery(), que recebe uma consulta de texto e retorna um único resultado de lugar, além de oferecer suporte ao uso de campos de dados de lugar.
  • O método findPlaceFromPhoneNumber(), que permite pesquisar um lugar usando um número de telefone e oferece suporte ao uso de campos de dados de lugar.
  • O método textSearch(), que usa uma consulta de texto e retorna uma lista de resultados de lugares. textSearch() é mais antigo e não oferece suporte ao uso de campos de dados de lugar.

A nova classe Place oferece o método Place.searchByText(), que permite pesquisar lugares usando uma consulta de texto ou um número de telefone e personalizar suas pesquisas usando uma seleção ampliada de campos de dados de lugar e tipos de lugar atualizados regularmente.

A tabela a seguir lista algumas das principais diferenças nos métodos de pesquisa de lugar entre a classe Place e PlacesService:

PlacesService (legado) Place (novo)
findPlaceFromQuery()
findPlaceFromPhoneNumber() 		searchByText()
FindPlaceFromQueryRequest
FindPlaceFromPhoneNumberRequest		 SearchByTextRequest
Opções de consulta limitadas. Opções de consulta mais amplas.
Requer o uso de um callback para processar o objeto de resultados e a resposta google.maps.places.PlacesServiceStatus. Usa promessas e funciona de forma assíncrona.
Requer uma verificação de PlacesServiceStatus. Nenhuma verificação de status necessária. É possível usar o tratamento de erros padrão.
Suporte apenas para viés de localização. Oferece suporte a viés e restrição de local.
Os campos de dados do lugar são formatados usando letras minúsculas. Os campos de dados de lugar são formatados usando letras maiúsculas e minúsculas.
Retorna um único resultado de lugar. Retorna até 20 resultados de locais.
Limitado a um conjunto fixo de tipos de lugar e campos de dados de lugar. Oferece uma seleção ampliada de tipos de lugar e campos de dados de lugar atualizados regularmente.
textSearch()
 searchByText()
Retorna todos os campos de dados disponíveis (um subconjunto dos campos aceitos). Não é possível restringir a campos específicos. Retorna apenas os campos de dados do lugar solicitados.

Comparação de código

Esta seção compara o código dos métodos de pesquisa de texto para ilustrar as diferenças entre o serviço Places e a classe Place. Os snippets de código mostram o código necessário em cada API para fazer uma solicitação de pesquisa baseada em texto.

Serviço do Places (legado)

O snippet de código abaixo mostra como usar o método findPlaceFromQuery() para procurar um lugar. A solicitação é síncrona e inclui uma verificação condicional em PlacesServiceStatus. Os campos de dados de lugar necessários são especificados no corpo da solicitação, que é definido antes de fazer a solicitação real.

function findPlaces() {
  const request = {
    query: "Museum of Contemporary Art Australia",
    fields: ["name", "geometry"],
  };

  // Create an instance of PlacesService.
  service = new google.maps.places.PlacesService(map);

  // Make a findPlaceFromQuery request.
  service.findPlaceFromQuery(request, (results, status) => {
    let place = results[0];
    if (status === google.maps.places.PlacesServiceStatus.OK && results) {
      if (!place.geometry || !place.geometry.location) return;

      const marker = new google.maps.Marker({
        map,
        position: place.geometry.location,
      });
      map.setCenter(place.geometry.location);
    }
  });
}

Saiba mais

Text Search (novo)

O snippet de código a seguir mostra como usar o método searchByText() para pesquisar lugares. A solicitação é assíncrona e não requer uma verificação de status. É possível usar a solução de erros padrão. Neste exemplo, a solicitação inclui um maxResultCount de 8 (o valor precisa estar entre 1 e 20). Essa função percorre os resultados e adiciona um marcador para cada um deles, ajustando os limites do mapa com base na posição dos marcadores. Como o método searchByText() usa o operador await, ele só pode ser usado dentro de uma função async.

async function findPlaces() {
  // Define a request.
  // The `fields` property is required; all others are optional.
  const request = {
    fields: ["displayName", "location", "businessStatus"],
    textQuery: "Tacos in Mountain View",
    includedType: "restaurant",
    locationBias: { lat: 37.4161493, lng: -122.0812166 },
    isOpenNow: true,
    language: "en-US",
    maxResultCount: 8,
    minRating: 3.2,
    region: "us",
    useStrictTypeFiltering: false,
  };

  // Call searchByText passing the request.
  const { places } = await google.maps.places.Place.searchByText(request);

  // Add a marker for each result.
  if (places.length) {
    const bounds = new google.maps.LatLngBounds();

    places.forEach((place) => {
      const markerView = new google.maps.marker.AdvancedMarkerElement({
        map,
        position: place.location,
        title: place.displayName,
      });

      bounds.extend(place.location);
      console.log(place);
    });
    map.fitBounds(bounds);
  } else {
    console.log("No results");
  }
}

O método searchByText() oferece suporte a muitas outras opções de solicitação em comparação com a versão anterior, incluindo:

  • includedType, que permite restringir as pesquisas a um tipo de lugar específico.
  • isOpenNow, que permite restringir as pesquisas para retornar apenas lugares que estão abertos.
  • minRating, que permite filtrar resultados abaixo do limite especificado (por exemplo, retornar apenas lugares com três estrelas ou mais).
  • locationRestriction, que omite resultados fora do local especificado. locationBias também é aceito.

Saiba mais