Place Details

Selecione a plataforma: Android iOS JavaScript Web Service

O SDK do Places para Android fornece informações valiosas ao seu app sobre os lugares, incluindo o nome e o endereço, o localização especificada como coordenadas de latitude/longitude, o tipo de lugar (como como boate, pet shop, museu) e muito mais. Para acessar essas informações local específico, use o ID de local, um identificador estável que identifica identifica um lugar.

Detalhes do lugar

O Place objeto fornece informações sobre um local específico. É possível receber Place das seguintes maneiras:

• Ligação PlacesClient.fetchPlace() – Consulte o guia sobre acessar um lugar pelo ID.
• Ligação PlacesClient.findCurrentPlace() – Consulte o guia sobre acessar o lugar atual.
  Enquanto PlacesClient.fetchPlace() oferece suporte a todos os campos de dados de lugar, PlacesClient.findCurrentPlace() oferece suporte apenas a um subconjunto de campos de dados de lugar. Para a lista de campos NOT compatível com findCurrentPlace(). Consulte Suporte a campos do SDK do Places para Android.

Ao solicitar um lugar, é necessário especificar quais dados retornar. Para fazer isso, transmita uma lista de Place.Field valores especificando os dados a serem retornados. Essa lista é importante porque afeta custo de cada solicitação.

Como os resultados de dados de lugar não podem ficar vazios, apenas aqueles com dados são retornado (por exemplo, se um lugar solicitado não tem fotos, o photos não estará presente no resultado).

O exemplo a seguir passa uma lista de três Valores de Place.Field para especificar os dados retornados por uma solicitação:

Kotlin

// Specify the fields to return.
val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)

Java

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
  

Acessar campos de dados do objeto Place

Depois de conseguir o objeto Place, use os métodos do objeto para acessar o campos de dados especificados na solicitação. Se o campo estiver ausente no objeto Place, o método relacionado retorna nulo. Veja abaixo exemplos de alguns dos métodos disponíveis. Para uma lista completa de todos os métodos, consulte a Place Referência da API.

• getAddress(): o endereço do local, em formato legível por humanos. .
• getAddressComponents() a List de componentes de endereço para este local. Esses componentes são fornecidos para extrair informações estruturadas sobre o endereço de um local, por exemplo de como encontrar a cidade em que um lugar está localizado. Não usar componentes para formatação de endereços; em vez disso, chame getAddress(), que fornece um endereço formatado localizado.
• getId(): o identificador textual do local. Lida sobre IDs de lugar no restante desta página.
• getLatLng(): a localização geográfica do lugar; com coordenadas de latitude e longitude.
• getName(): o nome do lugar.

• getOpeningHours() – O OpeningHours do lugar. Chame OpeningHours.getWeekdayText() para retornar um lista de strings que representam os horários de abertura e fechamento de cada dia da semana. Chame OpeningHours.getPeriods() para retornar uma lista de objetos period com informações mais detalhadas que são equivalente aos dados fornecidos por getWeekdayText().

  Observação : se um lugar estiver sempre aberto, o período é representado como domingo à meia-noite, e closeEvent é nulo.

  O objeto Place também contém o getCurrentOpeningHours() que retorna o horário de funcionamento de um lugar nos próximos sete dias, e getSecondaryOpeningHours() que retorna o horário de funcionamento secundário de um lugar nos próximos sete dias.

• isOpen(): um booleano que indica se o lugar é está aberta no momento. Se nenhum horário for especificado, o padrão será agora. isOpen só será retornado se Place.Field.UTC_OFFSET e Place.Field.OPENING_HOURS estão disponíveis. Para garantir precisão resultados, solicite os Place.Field.BUSINESS_STATUS e Place.Field.UTC_OFFSET campos na sua solicitação de lugar original. Se não for solicitado, presume-se que a empresa está operante. Assista a este vídeo para saber como usar isOpen com Place Details.

  Observação : esse método foi descontinuado. Em vez disso, use PlacesClient.isOpen(IsOpenRequest request) Para mais informações, consulte Conferir o status "aberto".

Alguns exemplos simples:

Kotlin

val name = place.name
val address = place.address
val location = place.latLng

      

Java

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

Obter local por ID

O ID de lugar é um indicador textual que identifica um local de forma exclusiva. Em SDK do Places para Android, é possível recuperar o ID de um local chamando Place.getId() O Serviço Place Autocomplete também retorna um ID de local para cada local que corresponde à consulta de pesquisa fornecida e filtrar. Você pode armazenar o ID de local e usá-lo para recuperar o Place novamente mais tarde.

Para encontrar um lugar por ID, chame PlacesClient.fetchPlace(), transmitindo um FetchPlaceRequest.

A API retorna uma FetchPlaceResponse em um Task O FetchPlaceResponse contém um Place que corresponde ao ID de lugar fornecido.

O exemplo de código a seguir mostra como chamar fetchPlace() para obter detalhes do lugar especificado.

Kotlin

// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

Java

// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

Observação:para mais informações sobre como inicializar o PlacesClient, consulte Inicialize o cliente da API Places.

Você pode usar um CancellationToken para tentar cancelar uma solicitação para qualquer uma das classes de solicitação (por exemplo, FetchPlaceRequest). O cancelamento é feito na medida do possível. Quando uma solicitação de cancelamento é emitida, nenhuma resposta é retornada. A emissão de um token de cancelamento NÃO garante que uma determinada solicitação será cancelado e ainda poderá ser cobrado pela solicitação mesmo que não for retornada.

Receber status aberto

O PlacesClient.isOpen(IsOpenRequest request) retorna um objeto IsOpenResponse indicando se o local está aberto no momento com base no horário especificado na chamada.

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

• Uma Place objeto ou uma string que especifica um ID de local.
  Observação: O objeto Place deve conter um objeto válido ID de lugar.
• Um valor de tempo opcional que especifica o tempo em milissegundos de 1970-01-01T00:00:00Z. Se nenhum horário for especificado, o padrão será agora.

Esse método exige que os seguintes campos existam no objeto Place:

• Place.Field.BUSINESS_STATUS
• Place.Field.CURRENT_OPENING_HOURS
• Place.Field.OPENING_HOURS
• Place.Field.UTC_OFFSET

Se esses campos não forem fornecidos no objeto Place ou se você transmitir um ID de lugar, o método usa PlacesClient.fetchPlace() para buscá-los. Para mais informações sobre como criar o objeto Place com os campos necessários, consulte Place Details.

Observação : a SKU Basic Data do Places é cobrada por chamadas para fetchPlace() por Place.Field.UTC_OFFSET e Place.Field.BUSINESS_STATUS. A SKU Contact Data do Places é cobrada por chamadas para fetchPlace() por Place.Field.CURRENT_OPENING_HOURS e Place.Field.OPENING_HOURS.

O exemplo a seguir determina se um lugar está aberto no momento. Neste exemplo, você só passa o ID de lugar para isOpen():

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    e.printStackTrace()
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen
}
// ...

      

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    e.printStackTrace();
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) ->
                isOpen = response.isOpen());
// ...

      

O próximo exemplo mostra como chamar isOpen() onde você transmite um objeto Place. O objeto Place precisa conter um ID de lugar válido:

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"
// Specify the required fields for an isOpen request.
val placeFields: List<Place.Field> = listOf(
    Place.Field.BUSINESS_STATUS,
    Place.Field.CURRENT_OPENING_HOURS,
    Place.Field.ID,
    Place.Field.OPENING_HOURS,
    Place.Field.UTC_OFFSET
)

val placeRequest: FetchPlaceRequest =
    FetchPlaceRequest.newInstance(placeId, placeFields)
val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest)
placeTask.addOnSuccessListener { placeResponse ->
    place = placeResponse.place

    val isOpenRequest: IsOpenRequest = try {
        IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis)
    } catch (e: IllegalArgumentException) {
        e.printStackTrace()
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = isOpenResponse.isOpen
    }
    // ...
}
// ...

      

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
// Specify the required fields for an isOpen request.
List<Place.Field> placeFields = new ArrayList<>(Arrays.asList(
        Place.Field.BUSINESS_STATUS,
        Place.Field.CURRENT_OPENING_HOURS,
        Place.Field.ID,
        Place.Field.OPENING_HOURS,
        Place.Field.UTC_OFFSET
));

FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

placeTask.addOnSuccessListener(
        (placeResponse) -> {
            Place place = placeResponse.getPlace();
            IsOpenRequest isOpenRequest;

            try {
                isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis());
            } catch (IllegalArgumentException e) {
                e.printStackTrace();
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> isOpen = isOpenResponse.isOpen());
            // ...
        });
// ...

      

Exibir atribuições no seu aplicativo

Quando seu aplicativo exibe informações sobre lugares, incluindo avaliações, ele também precisa exibir nenhuma atribuição. Para mais informações, consulte atribuições.

Mais informações sobre IDs de local

O ID de lugar usado no SDK do Places para Android é o mesmo identificador que é usado na API Places. Cada ID de local pode se referir a apenas um local, mas um único local pode ter mais mais de um ID de lugar. Há outras circunstâncias que podem fazer com que um lugar receber um novo ID de lugar. Por exemplo, isso pode acontecer se uma empresa mudar para um novo o local.

Ao solicitar um local especificando um ID de local, você pode ter a certeza de que você sempre receberá o mesmo lugar na resposta (se o lugar ainda existe). Observe, no entanto, que a resposta pode conter um ID de local que é diferente daquele em sua solicitação.

Para mais informações, consulte a visão geral do ID de lugar.