Yer Ayrıntıları

Platform seçin: Android iOS JavaScript Web Hizmeti

Android için Yerler SDK'sı uygulamanıza yerlerle ilgili zengin bilgiler sağlar. Bu bilgiler arasında yerin adı ve adresi, enlem/boylam koordinatları olarak belirtilen coğrafi konum, yer türü (gece kulübü, evcil hayvan mağazası, müze gibi) 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. Bir Place nesnesini aşağıdaki şekillerde tutabilirsiniz:

• Arayın PlacesClient.fetchPlace() – Kimliğe göre yer alma rehberine bakın.
• Arayın PlacesClient.findCurrentPlace() – Mevcut yeri edinme rehberine bakın.
  PlacesClient.fetchPlace() tüm yer verisi alanlarını desteklerken PlacesClient.findCurrentPlace() yer verisi alanlarının yalnızca bir alt kümesini destekler. findCurrentPlace() tarafından DESTEKLENMEYEN alanların listesi için Android için Yerler SDK'sı alanları desteği bölümüne bakın.

Bir yer isteğinde bulunduğunuzda, hangi yer verilerinin döndürüleceğini belirtmeniz gerekir. Bunu yapmak için döndürülecek verileri belirten Place.Field değerleri listesini iletin. Her isteğin maliyetini etkilediği için bu liste, önemli bir konudur.

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ı gösterilmez).

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

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 placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

Not: Android için Yerler SDK'sı ve Android için Yerler SDK'sı (Yeni) farklı fiyatlandırma modellerini destekler. Yani bir çağrının fiyatı, istediğiniz alanlara ve kullandığınız SDK sürümüne bağlıdır. Her iki SDK'yla ilgili ayrıntılı fiyatlandırma bilgileri için Kullanım ve Faturalandırma bölümünü inceleyin.

Yer nesnesi veri alanlarına erişim

Place nesnesini edindikten sonra, istekte belirtilen veri alanlarına erişmek için nesnenin yöntemlerini kullanın. Place nesnesinde alan yoksa ilgili yöntem null değerini döndürür. Aşağıda, kullanılabilir yöntemlerden birkaçı gösterilmektedir. Tüm yöntemlerin tam listesi için Place API referansına bakın.

• getAddress() – Yerin, kullanıcıların okuyabileceği biçimdeki adresidir.
• getAddressComponents() – Bu yer için List adres bileşenleri. Bu bileşenler, bir yerin adresi hakkında yapılandırılmış bilgileri çıkarmak için (ör. bir yerin bulunduğu şehri bulmak) sağlanır. Adres biçimlendirme için bu bileşenleri kullanmayın. Bunun yerine, yerelleştirilmiş biçimlendirilmiş adres sağlayan getAddress() işlevini çağırın.
• getId() – Yer için metinsel tanımlayıcıdır. Bu sayfanın geri kalanında yer kimlikleri hakkında daha fazla bilgi edinin.
• getLatLng() – Yerin enlem ve boylam koordinatları olarak belirtilen coğrafi konumu.
• getName() – Yerin adı.

• getOpeningHours() – Yere ait OpeningHours. Haftanın her günü açılış ve kapanış saatlerini temsil eden dizelerin listesini döndürmek için 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.

  Not: Bir yer her zaman açıksa dönem pazar gece yarısı olarak temsil edilir ve closeEvent null olur.

  Place nesnesi ayrıca bir yerin sonraki yedi gün içindeki çalışma saatlerini döndüren getCurrentOpeningHours() yöntemini ve bir yerin sonraki 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 boole değeridir. Herhangi bir saat belirtilmezse varsayılan değer olarak kullanılır. isOpen, yalnızca Place.Field.UTC_OFFSET ve Place.Field.OPENING_HOURS varsa döndürülür. Doğru sonuçlar elde etmek için orijinal yer isteğinizdeki Place.Field.BUSINESS_STATUS ve Place.Field.UTC_OFFSET alanlarını isteyin. İstekte bulunulmaması durumunda işletmenin faaliyette olduğu varsayılır. isOpen öğesinin Yer Ayrıntıları ile nasıl kullanılacağını öğrenmek için bu videoyu izleyin.

  Not: Bu yöntem kullanımdan kaldırılmıştır. Bunun yerine PlacesClient.isOpen(IsOpenRequest request) alanını kullanın. Daha fazla bilgi için Açık durumunu alma bölümüne bakın.

Birkaç basit örnek:

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

      

Sürüm 3.3.0'da eklenen Yer verilerine erişme

Android için Yerler SDK'sı sürüm 3.3.0 Place'e yeni veriler ekler:

• Yer türleri: Bir yerle ilişkili yeni tür değerleri.
• Yorumlar: Bir yer için en fazla beş yorum.
• Ad dil kodu: Bir yer adının dil kodu.

Aşağıdaki bölümlerde, bu yeni verilere nasıl erişileceği açıklanmaktadır.

Not: Yeni SDK yalnızca Java'daki yeni Place verilerini destekler.

Yeni yer türlerine erişin

Her yerin, kendisiyle ilişkili bir veya daha fazla type değeri olabilir. Android için Yerler SDK'sının 3.3.0 sürümü, birçok yeni tür değeri ekler. Tam liste için Genişletilmiş yer türleri bölümünü inceleyin.

Android için Yerler SDK'sının 3.2.0 ve önceki sürümlerinde, bir yerle ilişkilendirilmiş tür değerlerine erişmek için Place.getTypes() yöntemini kullanmıştınız. Place.getTypes(), Place.Types tarafından tanımlanan enum değerleri olarak bir tür listesi döndürür.

Place.getTypes() yöntemi, Android'in 3.3.0 sürümü için Yerler SDK'sı itibarıyla kullanımdan kaldırılmıştır. Kullanımdan kaldırma süresi boyunca bu hizmeti kullanmaya devam edebilirsiniz ancak uygulamalarınızı, bunun yerine Place.getPlaceTypes() kullanımına taşımanız gerekir.

Place.getPlaceTypes() yöntemi, tür değerlerini dize değerlerinin bir listesi olarak döndürür. Döndürülen değerler, Android için Yerler SDK'sı sürümünüze bağlıdır:

• Android için Yerler SDK'sı (Yeni): 3.3.0 sürümünde eklenen tüm yer türleri dahil olmak üzere, Yer Türleri (Yeni) sayfasında gösterilen Tablo A ve Tablo B tarafından tanımlanan dizeleri döndürür.
• Android için Yerler SDK'sı: 3.3.0 sürümünde eklenen yeni türleri içermeyen, Place.Types tarafından tanımlanan enum'ları döndürür.

İki SDK sürümü arasındaki temel farkları öğrenmek için SDK sürümünüzü seçme bölümünü inceleyin.

Yer yorumlarına erişme

Android için Yerler SDK'sı (Yeni), bir yerle ilgili yorum içeren Review sınıfını ekler. Place nesnesi en fazla beş yorum içerebilir.

Review sınıfı, ilişkilendirme ve yazar ilişkilendirmesi de içerebilir. Yorumu uygulamanızda gösterirseniz herhangi bir atıf veya yazar atıfını da göstermeniz gerekir. Daha fazla bilgi için Yorum görüntüleme başlıklı makaleyi inceleyin.

Place nesnesini yorumlarla doldurmak için şunları yapmanız gerekir:

1. Google Cloud projenizi oluştururken yeni SDK'yı etkinleştirin.
2. Bir etkinlik veya parça içinde yeni SDK'yı başlatın.
3. Yer ayrıntıları isteğinin alan listesine Place.Field.REVIEWS öğesini ekleyin.
4. PlacesClient.fetchPlace() numaralı telefonu arayın. Yorum alanı PlacesClient.findCurrentPlace() tarafından desteklenmiyor.
5. Place nesnesindeki yorum verileri alanına erişmek için Place.getReviews() yöntemini kullanın.

Yer adı dil koduna erişim

Mevcut Place.getName() yöntemi, bir yerin adını içeren metin dizesi döndürür. Place nesnesini yer adıyla doldurmak için yer ayrıntıları isteğinin alan listesine Place.Field.NAME öğesini eklemeniz gerekir.

Place nesnesi artık ad dizesinin dil kodunu içerir. Place nesnesini dil koduyla doldurmak için şunları yapmanız gerekir:

1. Google Cloud projenizi oluştururken yeni SDK'yı etkinleştirin.
2. Bir etkinlik veya parça içinde yeni SDK'yı başlatın.
3. İsteğin alan listesine Place.Field.NAME öğesini ekleyin. Bu değer, yanıtı hem yer adını hem de dil kodunu Place nesnesine ekleyecek şekilde yapılandırır.
4. PlacesClient.fetchPlace() numaralı telefonu arayın. PlacesClient.findCurrentPlace(), dil kodu alanını desteklemiyor.
5. Place nesnesindeki dil kodu alanına erişmek için Place.getNameLanguageCode() yöntemini kullanın.

Sürüm 3.3.0'da bölge kodunu ayarlama

Android için Yerler SDK'sı (Yeni), Yer Ayrıntıları'na bölge kodu isteği parametresini ekler. Bölge kodu, yanıtı biçimlendirmek için iki karakterli CLDR kodu değeri olarak kullanılır. Bu parametrenin arama sonuçları üzerinde de bir yanlılık etkisi olabilir. Varsayılan değer yoktur. Bölge kodunu ayarlamak için yeni SDK'yı etkinleştirmeniz gerekir.

Yanıttaki adres alanının ülke adı bölge koduyla eşleşirse ülke kodu adresten çıkarılır.

Çoğu CLDR kodu, bazı önemli istisnalar dışında ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk) ve ISO 3166-1 kodu "gb"'dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallığı" tüzel kişiliği için). Parametre, geçerli yasaya göre sonuçları etkileyebilir.

Kimliğe göre yer alma

Yer kimliği, bir yeri benzersiz şekilde tanımlayan metin biçimli bir tanımlayıcıdır. Android için Yerler SDK'sında bir yerin kimliğini Place.getId() çağırarak alabilirsiniz. Otomatik Yer 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 Place nesnesini daha sonra tekrar almak için kullanabilirsiniz.

Bir yeri kimliğe göre almak için FetchPlaceRequest geçtikten sonra PlacesClient.fetchPlace() numarasını arayın.

API, Task içinde bir 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 = "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.
    }
});

      

İstek sınıflarından herhangi birine (örneğin, FetchPlaceRequest) ait bir isteği iptal etmeyi denemek için CancellationToken kullanabilirsiniz. İptal işlemi, mümkün olan en iyi şekilde gerçekleştirilir. İptal isteği gönderildiğinde yanıt döndürülmez. İptal jetonu yayınlamak belirli bir isteğin iptal edileceğini garanti etmez ve hiçbir yanıt döndürülmese bile istek için ücret alınabilir.

Açık durumunu al

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

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

• Bir Place nesnesi veya yer kimliğini belirten bir dize.
  Not: Place nesnesi geçerli bir yer kimliği içermelidir.
• 1970-01-01T00:00:00Z arasındaki zamanı milisaniye cinsinden belirten isteğe bağlı zaman değeri. Herhangi bir saat belirtilmezse varsayılan değer olarak kullanılır.

Bu yöntem Place nesnesinde aşağıdaki alanların olması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ı getirmek için PlacesClient.fetchPlace() yöntemini kullanır. Gerekli alanlarla Yer nesnesini oluşturma hakkında daha fazla bilgi edinmek için Yer ayrıntıları bölümüne bakın.

Not: Yerler Temel Veri SKU'su, Place.Field.UTC_OFFSET vePlace.Field.BUSINESS_STATUS için fetchPlace() numaralı telefona yapılan aramalar için ücretlendirilir. Yerler Kişi Verileri SKU'su, fetchPlace() yapılan aramalar için Place.Field.CURRENT_OPENING_HOURS ve Place.Field.OPENING_HOURS için ücretlendirilir.

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

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

      

Sonraki örnekte, bir Place nesnesi ilettiğinizde 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 = "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());
            // ...
        });
// ...

      

İlişkilendirmeleri uygulamanızda gösterme

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

Yer kimlikleri hakkında daha fazla bilgi

Android için Yerler SDK'sında kullanılan yer kimliği, Places API'de kullanılan tanımlayıcıyla aynıdır. Her yer kimliği yalnızca bir yeri belirtebilir 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 bu durum, işletme yeni bir konuma taşınırsa yaşanabilir.

Bir yer kimliği belirterek bir yer isteğinde bulunduğunuzda yanıtta her zaman aynı yeri (yer hâlâ mevcutsa) alacağınızdan emin olabilirsiniz. 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ış konusuna göz atın.