Yer Ayrıntıları (eski)

Avrupa Ekonomik Alanı'ndaki (AEA) geliştiriciler

Places SDK for Android (Eski), uygulamanıza yerler hakkında zengin bilgiler sağlar. Bu bilgiler arasında yerin adı ve adresi, enlem/boylam koordinatları olarak belirtilen coğrafi konum, yerin türü (ör. gece kulübü, evcil hayvan mağazası, müze) ve daha fazlası yer alır. Belirli bir yerle ilgili bu bilgilere erişmek için, bir yeri benzersiz şekilde tanımlayan sabit bir tanımlayıcı olan yer kimliğini kullanabilirsiniz.

Yer ayrıntıları

Place nesnesi, belirli bir yer hakkında bilgi sağlar. PlacesClient.fetchPlace() yöntemini çağırarak bir Place nesnesi elde edebilirsiniz. Kimliğe göre yer alma kılavuzunu inceleyin.

Bir yer istediğinizde hangi yer verilerinin döndürüleceğini belirtmeniz gerekir. Bunun için, döndürülecek verileri belirten bir Place.Field değerleri listesi iletin. Bu liste, her isteğin maliyetini etkilediği için önemli bir husustur.

Yer verisi sonuçları boş olamayacağından yalnızca veri içeren yer sonuçları döndürülür. Örneğin, istenen bir yerin fotoğrafı yoksa sonuçta photos alanı bulunmaz.

Aşağıdaki örnekte, bir istek tarafından döndürülen verileri belirtmek için üç Place.Field değerinden oluşan bir liste iletilmektedir:

Kotlin

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

Java

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

Place nesnesi veri alanlarına erişme

Place nesnesini aldıktan sonra, istekte belirtilen veri alanlarına erişmek için nesnenin yöntemlerini kullanın. Alan, Place nesnesinde yoksa ilgili yöntem null değerini döndürür. Aşağıda, kullanılabilir yöntemlerden birkaçına dair örnekler gösterilmektedir.

  • getAddress(): Yerin okunabilir biçimdeki adresi.
  • getAddressComponents(): Bu yerin adres bileşenlerinin List. Bu bileşenler, bir yerin adresiyle ilgili yapılandırılmış bilgileri (ör. bir yerin bulunduğu şehir) ayıklamak için sağlanır. Adres biçimlendirme için bu bileşenleri kullanmayın. Bunun yerine, yerelleştirilmiş biçimlendirilmiş bir adres sağlayan getAddress() yöntemini çağırın.
  • getId(): Yerin metin tanımlayıcısı. Bu sayfanın geri kalanında yer kimlikleri hakkında daha fazla bilgi edinebilirsiniz.
  • getLatLng(): Enlem ve boylam koordinatları olarak belirtilen, yerin coğrafi konumu.
  • getName(): Yerin adı.

  • getOpeningHours(): Yerin OpeningHours. Haftanın her günü için açılış ve kapanış saatlerini temsil eden dize listesini döndürmek üzere OpeningHours.getWeekdayText() yöntemini çağırın. getWeekdayText() tarafından sağlanan verilere eşdeğer, daha ayrıntılı bilgiler içeren period nesnelerinin listesini döndürmek için OpeningHours.getPeriods() yöntemini çağırın.

    Place nesnesi, bir yerin önümüzdeki yedi gün içindeki çalışma saatlerini döndüren getCurrentOpeningHours() yöntemini ve bir yerin önümüzdeki yedi gün içindeki ikincil çalışma saatlerini döndüren getSecondaryOpeningHours() yöntemini de içerir.

  • isOpen(): Yerin şu anda açık olup olmadığını belirten bir boole değeri. Herhangi bir zaman belirtilmezse varsayılan olarak geçerli zaman kullanılır. isOpen yalnızca hem Place.Field.UTC_OFFSET hem de Place.Field.OPENING_HOURS mevcutsa döndürülür. Doğru sonuçlar elde etmek için orijinal yer isteğinizde Place.Field.BUSINESS_STATUS ve Place.Field.UTC_OFFSET alanlarını isteyin. İstenmediği takdirde işletmenin faal olduğu varsayılır. isOpen özelliğini Yer Ayrıntıları ile nasıl kullanacağınızı öğrenmek için bu videoyu izleyin.

Bazı örnekler:

Kotlin

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

Java

                    final CharSequence name = place.getDisplayName();
                    final CharSequence address = place.getFormattedAddress();
                    final LatLng location = place.getLocation();

Kimliğe göre yer alma

Yer kimliği, bir yeri benzersiz şekilde tanımlayan metin tabanlı bir tanımlayıcıdır. Android için Yerler SDK'sında, Place.getId() yöntemini çağırarak bir yerin kimliğini alabilirsiniz. Yer Adı Otomatik Tamamlama hizmeti, sağlanan arama sorgusu ve filtreyle eşleşen her yer için bir yer kimliği de döndürür. Yer kimliğini depolayabilir ve daha sonra Place nesnesini tekrar almak için kullanabilirsiniz.

Kimliğe göre bir yer almak için PlacesClient.fetchPlace() işlevini çağırın ve FetchPlaceRequest değerini iletin.

API, bir Task içinde FetchPlaceResponse döndürür. FetchPlaceResponse, sağlanan yer kimliğiyle eşleşen bir Place nesnesi içerir.

Aşağıdaki kod örneğinde, belirtilen yerle ilgili ayrıntıları almak için fetchPlace() çağrısı gösterilmektedir.

Kotlin

// Define a Place ID.
val placeId = PlaceIdProvider.getRandomPlaceId()

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

// 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

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location,
                location.latitude,
                location.longitude,
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            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 = PlaceIdProvider.getRandomPlaceId();

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

// 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();

                    final CharSequence name = place.getDisplayName();
                    final CharSequence address = place.getFormattedAddress();
                    final LatLng location = place.getLocation();

                    binding.placeName.setText(name);
                    binding.placeAddress.setText(address);
                    if (location != null) {
                        binding.placeLocation.setText(
                                getString(
                                        R.string.place_location,
                                        location.latitude,
                                        location.longitude));
                    } else {
                        binding.placeLocation.setText(null);
                    }

                    Log.i(TAG, "Place found: " + place.getDisplayName());
                })
        .addOnFailureListener(
                (exception) -> {
                    if (exception instanceof ApiException apiException) {
                        final String message =
                                getString(
                                        R.string.place_not_found,
                                        apiException.getMessage());
                        binding.placeName.setText(message);
                        Log.e(TAG, "Place not found: " + exception.getMessage());
                        final int statusCode = apiException.getStatusCode();
                        // TODO: Handle error with given status code.
                    }
                });

Açık durumunu alma

PlacesClient.isOpen(IsOpenRequest request) yöntemi, çağrıda belirtilen zamana göre yerin şu anda açık olup olmadığını gösteren bir IsOpenResponse nesnesi döndürür.

Bu yöntem, aşağıdakileri içeren IsOpenRequest türünde tek bir bağımsız değişken alır:

  • Place nesnesi veya yer kimliğini belirten bir dize.
  • 1970-01-01T00:00:00Z tarihinden itibaren milisaniye cinsinden zamanı belirten isteğe bağlı bir zaman değeri. Herhangi bir zaman belirtilmezse varsayılan olarak geçerli zaman kullanılır.

Bu yöntem, Place nesnesinde aşağıdaki alanların bulunmasını gerektirir:

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

Bu alanlar Place nesnesinde sağlanmazsa veya bir yer kimliği iletirseniz yöntem, bunları almak için PlacesClient.fetchPlace() yöntemini kullanır. Gerekli alanları içeren Place nesnesini oluşturma hakkında daha fazla bilgi için Yer ayrıntıları başlıklı makaleyi inceleyin.

Aşağıdaki örnekte, bir yerin şu anda açık olup olmadığı belirlenmektedir. Bu örnekte, isOpen() yöntemine yalnızca yer kimliğini iletirsiniz:

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = PlaceIdProvider.getRandomPlaceId()

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    Log.e("PlaceIsOpen", "Error: " + e.message)
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen ?: false
    binding.isOpenByIdResult.text = getString(R.string.is_open_by_id, isOpen.toString())
    Log.d("PlaceIsOpen", "Is open by ID: $isOpen")
}
// ...

Java

@NonNull Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    Log.e("PlaceIsOpen", "Error: " + e.getMessage());
    return;
}

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

placeTask.addOnSuccessListener(
        (response) -> {
            final boolean isOpen = Boolean.TRUE.equals(response.isOpen());
            binding.isOpenByIdResult.setText(
                    getString(R.string.is_open_by_id, String.valueOf(isOpen)));
            Log.d("PlaceIsOpen", "Is open by ID: " + isOpen);
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByIdResult.setText(
                    getString(R.string.is_open_by_id, "Error: " + exception.getMessage()));
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
        });

Bir sonraki örnekte, Place nesnesini ilettiğiniz isOpen() çağrısı gösterilmektedir. Place nesnesi geçerli bir yer kimliği içermelidir:

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = PlaceIdProvider.getRandomPlaceId()
// 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.DISPLAY_NAME,
)

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) {
        Log.e("PlaceIsOpen", "Error: " + e.message)
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = when (isOpenResponse.isOpen) {
            true -> getString(R.string.is_open)
            else -> getString(R.string.is_closed)
        }
        binding.isOpenByObjectResult.text = getString(
            R.string.is_open_by_object,
            place.displayName,
            isOpen,
        )
        Log.d("PlaceIsOpen", "Is open by object: $isOpen")
    }
    // ...
}
// ...

Java

@NonNull Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
// 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.DISPLAY_NAME));

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) {
                Log.e("PlaceIsOpen", "Error: " + e.getMessage());
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> {
                        final boolean isOpen = Boolean.TRUE.equals(isOpenResponse.isOpen());
                        binding.isOpenByObjectResult.setText(
                                getString(
                                        R.string.is_open_by_object,
                                        place.getDisplayName(),
                                        String.valueOf(isOpen)));
                        Log.d("PlaceIsOpen", "Is open by object: " + isOpen);
                    });
            isOpenTask.addOnFailureListener(
                    (exception) -> { // also update the result text field
                        binding.isOpenByObjectResult.setText(
                                getString(
                                        R.string.is_open_by_object,
                                        place.getDisplayName(),
                                        "Error: " + exception.getMessage()));
                        Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
                    });
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByObjectResult.setText("Error: " + exception.getMessage());
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());

Uygulamanızda ilişkilendirmeleri gösterme

Uygulamanız, yer yorumları da dahil olmak üzere yer bilgilerini gösterdiğinde tüm atıfları da göstermelidir. Daha fazla bilgi için atıflar bölümüne bakın.

Yer kimlikleri hakkında daha fazla bilgi

Android için Yerler SDK'sında (Eski) kullanılan yer kimliği, Places API'de (Eski) kullanılan tanımlayıcıyla aynıdır. Her yer kimliği yalnızca bir yeri ifade edebilir ancak tek bir yerin birden fazla yer kimliği olabilir. Bir yerin yeni bir yer kimliği almasına neden olabilecek başka durumlar da vardır. Örneğin, bir işletme yeni bir konuma taşındığında bu durumla karşılaşılabilir.

Bir yeri, yer kimliğini belirterek istediğinizde yanıtta her zaman aynı yeri alacağınızdan emin olabilirsiniz (yer hâlâ mevcutsa). Ancak yanıtın, isteğinizdekinden farklı bir yer kimliği içerebileceğini unutmayın.

Daha fazla bilgi için yer kimliğine genel bakış başlıklı makaleyi inceleyin.