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 classe PlacesService (legada) e mostramos 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 aceita o 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 é 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 ampliada de campos de dados e tipos de lugar atualizados regularmente.

A tabela a seguir lista algumas das principais diferenças nos métodos de Place Search 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.
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. Não é necessário verificar o status, é possível usar o tratamento de erros padrão. Saiba mais.
Oferece suporte apenas à polarização de local. Oferece suporte à polarização e à restrição de local.
Os campos de dados de lugar são formatados usando snake case. Os campos de dados de lugar são formatados usando letras concatenadas.
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 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 pode ser restrito a campos específicos. Retorna apenas os campos de dados de lugar solicitados.

Comparação de código

Nesta seção, comparamos o código dos métodos de Text Search 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 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 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 o uso do método searchByText() para pesquisar lugares. A solicitação é assíncrona e não requer uma verificação de status (é possível usar o tratamento 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, 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() é compatível com 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, retornar apenas lugares com três estrelas ou mais).
  • locationRestriction, que omite resultados fora do local especificado (locationBias também é aceito).

Saiba mais