Migrar para o novo Place Search

Desenvolvedores do Espaço Econômico Europeu (EEE)

Nesta página, explicamos as diferenças entre os recursos de pesquisa de lugares baseada em texto na classe Place (nova) e na PlacesService (legada) e fornecemos alguns snippets de código para comparação.

O PlacesService legado tem os seguintes métodos de pesquisa baseados 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. O textSearch() é mais antigo e não é compatível com o 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, além de personalizar as pesquisas com uma seleção expandida de campos de dados e tipos de lugares 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 abrangentes.
Exige 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, pode usar o tratamento de erros padrão. Saiba mais.
Aceita apenas o viés de local. Tem suporte para restrição e viés de local.
Os campos de dados de lugar são formatados usando snake case. Os campos de dados de lugar são formatados usando camel case.
Retorna um único resultado de lugar. Retorna até 20 resultados de lugares.
Limitado a um conjunto fixo de tipos de lugar e campos de dados de lugar. Oferece uma seleção expandida de tipos de lugares e campos de dados de lugares atualizados regularmente.
textSearch()
 searchByText()
Retorna todos os campos de dados disponíveis (um subconjunto dos campos aceitos) e não pode ser restringido a campos específicos. Retorna apenas os campos de dados de 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 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 a seguir mostra o uso do método findPlaceFromQuery() para pesquisar 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 da 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 o uso do método searchByText() para pesquisar lugares. A solicitação é assíncrona e não exige uma verificação de status. O tratamento de erros padrão pode ser usado. Neste exemplo, a solicitação inclui um maxResultCount de 8 (o valor precisa estar entre 1 e 20). Essa função faz um loop pelos resultados e adiciona um marcador para cada um, 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 em 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 muito mais 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, só retornar lugares com três estrelas ou mais.
  • locationRestriction, que omite resultados fora do local especificado (locationBias também é compatível).

Saiba mais