Pesquisa de local próximo (Novo)

Selecione a plataforma: Android iOS JavaScript Web Service

Esse recurso exige que você ative API Places (nova), a próxima geração da API Places. Para mais informações, consulte Ative as APIs.

Uma solicitação de Nearby Search (novo) usa como entrada a região a ser pesquisada especificado como um círculo, definido pelas coordenadas de latitude e longitude do ponto central do círculo e o raio em metros. A solicitação retorna uma lista de locais correspondentes, cada um representado por uma GMSPlace , dentro da área de pesquisa especificada.

Por padrão, a resposta contém locais de todos os tipos dentro da área de pesquisa. Também é possível filtrar a resposta especificando uma lista de tipos de lugar a serem incluídos ou excluídos explicitamente do resposta. Por exemplo, você pode especificar para incluir apenas esses locais na resposta que sejam do tipo "restaurante", "padaria" e "café", ou excluir todos os lugares do tipo "escola".

Solicitações do Nearby Search (novo)

Faça uma solicitação do Nearby Search chamando GMSPlacesClient searchNearbyWithRequest:, transmitir um GMSPlaceSearchNearbyRequest objeto que define os parâmetros de solicitação e um método de retorno de chamada, do tipo GMSPlaceSearchNearbyResultCallback, para lidar com a resposta.

O objeto GMSPlaceSearchNearbyRequest especifica todos os obrigatório e opcional parâmetros para a solicitação. Os parâmetros obrigatórios incluem:

• A lista de campos a serem retornados no objeto GMSPlace, também chamado de máscara de campo, conforme definido pela GMSPlaceProperty Se você não especificar pelo menos um campo na lista ou se omitir na lista de campos, a chamada retornará um erro.
• a restrição de local, ou seja, o círculo que define a área de pesquisa;

Este exemplo de solicitação de pesquisa por perto especifica que a resposta os objetos GMSPlace contêm o nome do lugar (GMSPlacePropertyName) e as coordenadas dele (GMSPlacePropertyCoordinate) para cada objeto GMSPlace na pesquisa resultados. Ele também filtra a resposta para retornar apenas lugares do tipo "restaurante". e "café".

Swift

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchNearby(with: request, callback: callback)

Objective-C

// Array to hold the places in the response
_placeResults = [NSArray array];

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

[_placesClient searchNearbyWithRequest:request
  callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
        // Get list of places.
        _placeResults = places;
    }
  }
];

SDK do Places Swift para iOS (pré-lançamento)

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Respostas do Nearby Search

A API Nearby Search retorna uma matriz de correspondências na forma de GMSPlace objetos, com um objeto GMSPlace por lugar correspondente.

Observação : campos do objeto GMSPlace de resposta não pode ficar em branco. Por exemplo, se a lista de campos incluir GMSPlacePropertyPhotos para solicitar o campo photos e o campo photos na resposta estiver vazio, será omitido do objeto GMSPlace de resposta.

Receber status aberto

O objeto GMSPlacesClient contém uma função de membro chamada isOpenWithRequest (isOpenRequest no Swift e isPlaceOpenRequest no GooglePlacesSwift) que retorna uma resposta indicando se o lugar está aberto no momento, com base no horário especificado na chamada.

Observação:as funções descontinuadas GMSPlace isOpen: e GMSPlace isOpenAtDate: podem não ser precisas e não devem ser usadas com a API Places (nova).

Esse método usa um único argumento do tipo GMSPlaceIsOpenWithRequest que contém:

• Um objeto GMSPlace ou uma string que especifica um ID de lugar. Para mais informações sobre como criar o objeto de lugar com os campos necessários, consulte Detalhes do lugar.
  
  Observação:o objeto Place precisa conter um ID de lugar válido.
• Um objeto NSDate (Obj-C) ou Date (Swift) opcional que especifica o horário da verificação. Se nenhum horário for especificado, o padrão será agora.
• Um método GMSPlaceOpenStatusResponseCallback para gerenciar a resposta.
>

.

O método GMSPlaceIsOpenWithRequest exige que os seguintes campos sejam definidos no objeto GMSPlace:

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

Se esses campos não forem fornecidos no objeto Place ou se você transmitir um ID de lugar, o método vai usar GMSPlacesClient GMSFetchPlaceRequest: para buscá-los.

isOpenWithRequest resposta

isOpenWithRequest retorna um objeto GMSPlaceIsOpenResponse contendo um valor booleano chamado status, que indica se a empresa está aberta, fechada ou se o status é desconhecido.

Idioma	Valor se aberto	Valor se fechado	Valor se o status for desconhecido
Swift	.open	.closed	.unknown
Objective-C	GMSPlaceOpenStatusOpen	GMSPlaceOpenStatusClosed	GMSPlaceOpenStatusUnknown
GooglePlacesSwift (pré-lançamento)	true	false	nil

Faturamento de isOpenWithRequest

• Os campos GMSPlacePropertyUTCOffsetMinutes e GMSPlacePropertyBusinessStatus são cobrados na SKU de dados básicos. O restante do horário de funcionamento é cobrado com base na SKU do Place Details (Advanced).
• Se o objeto GMSPlace já tiver esses campos de uma solicitação anterior, não vai haver outra cobrança.
• Aviso: se o objeto GMSPlace não tiver esses campos, você vai receber uma nova cobrança pela SKU Basic Data. O restante do horário de funcionamento é cobrado com base na SKU do Place Details (Advanced). Caso seu projeto use isOpenWithRequest, recomendamos buscar os detalhes necessários de lugar.

Exemplo: fazer uma solicitação GMSPlaceIsOpenWithRequest

O exemplo a seguir mostra como inicializar um GMSPlaceIsOpenWithRequest em um objeto GMSPlace.

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];
  
          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }
  
            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

GooglePlacesSwift

          let isOpenRequest = IsPlaceOpenRequest(place: place)
          switch await placesClient.isPlaceOpen(with: isOpenRequest) {
            case .success(let isOpenResponse):
              switch isOpenResponse.status {
                case true:
                  // Handle open
                case false:
                  // Handle closed
                case nil:
                  // Handle unknown
            case .failure(let placesError):
              // Handle error
          }
          

Parâmetros obrigatórios

Use o objeto GMSPlaceSearchNearbyRequest para especificar os parâmetros necessários para na pesquisa.

• Lista de campos

  Ao solicitar detalhes do lugar, você deve especificar os dados que retornar no objeto GMSPlace do lugar como uma máscara de campo. Para definir máscara de campo, transmite uma matriz de valores da GMSPlaceProperty ao objeto GMSPlaceSearchNearbyRequest. O mascaramento de campo é uma prática recomendada de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento e cobranças de faturamento desnecessários.

  Especifique um ou mais dos seguintes campos:

  • Os campos a seguir acionam o SKU do Nearby Search (Basic):

    GMSPlacePropertyAddressComponents, GMSPlacePropertyBusinessStatus, GMSPlacePropertyCoordinate, GMSPlacePropertyFormattedAddress, GMSPlacePropertyName, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyPhotos, GMSPlacePropertyPlaceID, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyViewport, GMSPlacePropertyWheelchairAccessibleEntrance

  • Os campos a seguir acionam o SKU do Nearby Search (Avançado):

    GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

  • Os campos a seguir acionam o SKU do Nearby Search (Preferencial):

    GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummary, GMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine, GMSPlacePropertyTakeout

  O exemplo a seguir passa uma lista de dois valores de campo para especificar que o objeto GMSPlace retornado por uma solicitação contém o Campos name e placeID:

  Swift

  // Specify the place data types to return.
  let fields: [GMSPlaceProperty] = [.placeID, .name]
          

  Objective-C

  // Specify the place data types to return.
  NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
          

  SDK do Places Swift para iOS (pré-lançamento)

  // Specify the place data types to return.
  let fields: [PlaceProperty] = [.placeID, .displayName]
          

• locationRestriction

  Uma GMSPlaceLocationRestriction objeto que define a região a ser pesquisada especificada como um círculo, definido pelo ponto central e em metros. O raio deve estar entre 0,0 e 50.000,0, inclusive. O raio padrão é 0,0. É necessário defini-lo na solicitação para um valor maior que 0,0.

Parâmetros opcionais

Use o objeto GMSPlaceSearchNearbyRequest para especificar os parâmetros opcionais do na pesquisa.

• allowedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

  Permite especificar uma lista de tipos de tipos Tabela A usada para filtrar nos resultados da pesquisa. Até 50 tipos podem ser especificados em cada categoria de restrição.

  Observação: os valores em Tabela B são retornados apenas na resposta. Não é possível usar valores em Tabela B como filtro.

  Um lugar só pode ter um único tipo principal dos tipos Tabela A associada a reimplantá-lo. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house". Usar includedPrimaryTypes e excludedPrimaryTypes para filtrar os resultados o tipo principal de um lugar.

  Um lugar também pode ter vários valores de tipo de tipos. Tabela A associados a ele. Por exemplo, um restaurante pode ter os seguintes tipos: "seafood_restaurant", "restaurant" e "food". "point_of_interest", "establishment". Usar o includedTypes e excludedTypes para filtrar os resultados na lista de tipos associados a de um lugar.

  Quando você especifica um tipo principal geral, como "restaurant" ou "hotel", a resposta pode conter locais com um tipo principal mais específico do que o especificado. Por exemplo, você especifica a inclusão de um tipo primário de "restaurant": A resposta pode então conter locais com um tipo primário de "restaurant", mas a resposta também pode conter locais com um nome tipo primário, como "chinese_restaurant" ou "seafood_restaurant".

  Se uma pesquisa for especificada com várias restrições de tipo, apenas lugares que satisfaçam todas as restrições são retornadas. Por exemplo, se você especificar {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, o Os lugares retornados oferecem serviços relacionados ao "restaurant", mas não funcionam principalmente como um "steak_house".

  Se você omitir includedTypes, excludedTypes, includedPrimaryTypes e excludedPrimaryTypes da solicitação; a pesquisa retorna lugares de todos os tipos dentro dos limites de restrição de local.

  includedTypes

  Uma lista dos tipos de lugar de Tabela A a ser pesquisada. Se esse parâmetro for omitido, lugares de todos os tipos serão retornados.

  excludedTypes

  Uma lista de tipos de lugar de Tabela A para excluir de uma pesquisa.

  Se você especificar o includedTypes (como "school") e o excludedTypes (como "primary_school") na solicitação, depois o a resposta inclui lugares categorizados como "school", mas não como "primary_school". A resposta inclui locais que correspondem a pelo menos um dos a includedTypes e nenhuma da excludedTypes.

  Se houver algum tipo conflitante, como um tipo que aparece em includedTypes e excludedTypes, será retornado um erro INVALID_REQUEST.

  includedPrimaryTypes

  Uma lista dos principais tipos de lugar de Tabela A para incluir em uma pesquisa.

  excludedPrimaryTypes

  Uma lista dos principais tipos de lugar de Tabela A a ser excluída de uma pesquisa.

  Se houver algum tipo principal conflitante, como um tipo que aparece includedPrimaryTypes e excludedPrimaryTypes, uma INVALID_ARGUMENT será retornado.

• maxResultCount

  Especifica o número máximo de resultados de lugar a serem retornados. Precisa estar entre 1 e 20 (padrão).

• rankPreference

  O tipo de classificação a ser usado. Se esse parâmetro for omitido, os resultados serão classificados por popularidade. Pode ser uma das seguintes opções:

  • .popularity (padrão) classifica os resultados com base na popularidade.
  • .distance Classifica os resultados em ordem crescente de distância do em um local específico.

• regionCode

  O código da região usado para formatar a resposta, especificado como um de dois caracteres. Não há valor padrão.

  Se o nome do país do campo formattedAddress na resposta corresponder ao regionCode, o código do país é omitido do formattedAddress. Esse parâmetro não tem efeito sobre adrFormatAddress, que sempre inclui o país nome, ou em shortFormattedAddress, que nunca o inclui.

  A maioria dos códigos CLDR é idêntica códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente para os "Reino Unido da Grã-Bretanha e Irlanda do Norte"). O parâmetro pode afetar os resultados com base na legislação aplicável.

Exibir atribuições no seu aplicativo

Quando o app exibe informações recebidas de GMSPlacesClient, como fotos e avaliações, o app também precisará exibir as atribuições necessárias.

Por exemplo, a propriedade reviews do objeto GMSPlacesClient. contém uma matriz de até cinco GMSPlaceReview objetos. Cada objeto GMSPlaceReview pode conter atribuições e atribuições de autor. Se você exibir a avaliação no seu app, também deverá mostrar as atribuições ou os autores atribuição.

Para mais informações, consulte a documentação atribuições.