Android için Yerler SDK'sı, uygulamanıza 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) gibi zengin bilgiler sağlar. 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()
– Geçerli yeri bulma rehberine 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 bir Place.Field değerleri listesini iletin. Bu liste, her isteğin maliyetini etkilediği için önemlidir.
Yer verisi sonuçları boş bırakılamayacağı için yalnızca veri içeren yer sonuçları döndürülür (örneğin, istenen bir yerde 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 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 ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Yer nesnesi veri alanlarına erişim
Place
nesnesini aldıktan sonra istekte belirtilen veri alanlarına erişmek için nesnenin yöntemlerini kullanın. Place
nesnesinde alan yoksa ilgili yöntem boş sonucunu döndürür. Aşağıda, mevcut 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çinList
adres bileşeni. Bu bileşenler, bir yerin adresi ile ilgili yapılandırılmış bilgileri ayıklamak (örneğin, bir yerin bulunduğu şehri bulmak) amacıyla sağlanır. Adres biçimlendirme için bu bileşenleri kullanmayın. Bunun yerine, yerelleştirilmiş biçimlendirilmiş adres sağlayangetAddress()
yöntemini çağırın.getId()
– Yerin metinsel tanımlayıcısı. Bu sayfanın geri kalanında yer kimlikleri hakkında daha fazla bilgi edinebilirsiniz.getLatLng()
– Yerin, enlem ve boylam koordinatları olarak belirtilen coğrafi konumu.getName()
– Yerin adı.getOpeningHours()
– Yere aitOpeningHours
. Haftanın her günü açılış ve kapanış saatlerini temsil eden dizelerin listesini döndürmek içinOpeningHours.getWeekdayText()
yöntemini çağırın.getWeekdayText()
tarafından sağlanan verilere eşdeğer daha ayrıntılı bilgiler içerenperiod
nesnelerinin listesini döndürmek içinOpeningHours.getPeriods()
yöntemini çağırın.Place
nesnesi, bir yerin sonraki yedi gündeki çalışma saatlerini döndürengetCurrentOpeningHours()
yöntemini ve bir yerin sonraki yedi gündeki ikincil çalışma saatlerini döndürengetSecondaryOpeningHours()
yöntemini de içerir.isOpen()
– Yerin şu anda açık olup olmadığını belirten boole değeridir. Herhangi bir saat belirtilmezse varsayılan olarak şimdiki zaman kullanılır.isOpen
, yalnızca hemPlace.Field.UTC_OFFSET
hem dePlace.Field.OPENING_HOURS
varsa döndürülür. Doğru sonuçlar elde etmek için orijinal yer isteğinizdePlace.Field.BUSINESS_STATUS
vePlace.Field.UTC_OFFSET
alanlarını isteyin. İstekte bulunulmazsa işletmenin faaliyette olduğu varsayılır. Yer Ayrıntıları ileisOpen
özelliğini nasıl kullanacağınızı öğrenmek için bu videoyu izleyin.
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();
3.3.0 sürümünde 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 yerin adı için dil kodu.
Bu verilere erişmek üzere Android için Yerler SDK'sını (Yeni) etkinleştirmelisiniz. İ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.
Aşağıdaki bölümlerde, bu yeni verilere nasıl erişileceği açıklanmaktadır.
Yeni yer türlerine erişin
Her yerin kendisiyle ilişkilendirilmiş bir veya daha fazla type değeri olabilir. Android sürüm 3.3.0 için Yerler SDK'sı birçok yeni tür değeri ekler. Tam liste için Genişletilmiş yer türleri konusuna bakın.
Android'in 3.2.0 ve önceki sürümleri için Yerler SDK'sında bir yerle ilişkili tür değerlerine erişmek için Place.getTypes()
yöntemini kullandınız. Place.getTypes()
, Place.Types
tarafından tanımlanan enum değerleri olarak bir tür listesi döndürür.
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): Sürüm 3.3.0'da eklenen tüm yer türleri de dahil olmak üzere, Yer Türleri (Yeni) seçeneğinde 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ı, ayrıca bir atıf ve yazar ilişkilendirmesi de içerebilir. Yorumu, uygulamanızda gösterirseniz herhangi bir atıf veya yazar ilişkilendirmesini de 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:
- Google Cloud projenizi oluştururken yeni SDK'yı etkinleştirin.
- Bir etkinlik veya parça içinde yeni SDK'yı başlatın.
- Yer ayrıntıları isteğinin alan listesine
Place.Field.REVIEWS
kodunu ekleyin. PlacesClient.fetchPlace()
numaralı telefonu arayın. Yorum alanıPlacesClient.findCurrentPlace()
tarafından desteklenmiyor.Place
nesnesindeki yorum verileri alanına erişmek içinPlace.getReviews()
yöntemini kullanın.
Yer adı dil koduna erişim
Mevcut Place.getName()
yöntemi, bir yerin adını içeren bir 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 yapmanız gerekenler:
- Google Cloud projenizi oluştururken yeni SDK'yı etkinleştirin.
- Bir etkinlik veya parça içinde yeni SDK'yı başlatın.
Place.Field.NAME
özelliğini isteğin alan listesine ekleyin. Bu değer, yanıtı hem yer adını hem de dil kodunuPlace
nesnesine ekleyecek şekilde yapılandırır.PlacesClient.fetchPlace()
numaralı telefonu arayın.PlacesClient.findCurrentPlace()
, dil kodu alanını desteklemiyor.Place
nesnesindeki dil kodu alanına erişmek içinPlace.getNameLanguageCode()
yöntemini kullanın.
Sürüm 3.3.0'da bölge kodunu ayarlama
Android için Yerler SDK'sı (Yeni), bölge kodu isteği parametresini Yer Ayrıntıları'na ekler. Bölge kodu, yanıtı biçimlendirmek için kullanılır ve iki karakterli CLDR kodu değeriyle belirtilir. Bu parametrenin arama sonuçları üzerinde de sapma 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.
Bazı önemli istisnalar dışında CLDR kodlarının çoğu ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk), ISO 3166-1 kodu ise "gb"'dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallık'ı" için kullanılır). 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ğrısı yaparak 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()
yöntemini 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. } });
Açık olma durumunu alma
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 dize. - 1970-01-01T00:00:00Z arasındaki zamanı milisaniye cinsinden belirten isteğe bağlı bir saat değeri. Herhangi bir saat belirtilmezse varsayılan olarak şimdiki 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ı getirmek için PlacesClient.fetchPlace()
yöntemini kullanır. Gerekli alanlarla Yer nesnesi oluşturma hakkında daha fazla bilgi edinmek için Yer ayrıntıları konusuna bakın.
Aşağıdaki örnek, bir yerin şu anda açık olup olmadığını belirler. Bu örnekte, yer kimliğini yalnızca isOpen()
öğesine geçirirsiniz:
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
nesnesini ilettiğiniz yerde 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österin
Uygulamanız, yer yorumları dahil olmak üzere yer bilgilerini görüntülediğinde, uygulamanın tüm atıfları da göstermesi gerekir. 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 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 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 bu durum, bir işletme yeni bir konuma taşınırsa ortaya çıkabilir.
Bir yer kimliği belirterek yer isteğinde bulunduğunuzda, yanıtta her zaman aynı yeri alacağınızdan (yer hâlâ mevcutsa) 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ış konusunu inceleyin.