İstek parametreleri

Bu belgede, Places Aggregate API'nin istek parametreleri açıklanmakta ve bu hizmeti kullanmayla ilgili analizler ve en iyi uygulamalar yer almaktadır.

Places Aggregate API, birkaç önemli işlevi gerçekleştirmenize olanak tanır:

• Yerleri sayma: Konum türü, faaliyet durumu, fiyat düzeyi ve puanlar gibi belirli ölçütlerle eşleşen yerlerin sayısını belirleyin.
• Yer ayrıntılarını alma: Belirtilen filtreleri karşılayan yerlerin adlarını alın, ardından Places API'yi kullanarak daha ayrıntılı bilgiler alın.
• Esnek filtreleme: Hassas toplamlar elde etmek için kapsamlı filtreler uygulayın. Kullanılabilir filtreler şunlardır:
  • Coğrafi alan (daire, bölge veya özel poligon)
  • Yer türleri
  • Faaliyet durumu
  • Fiyat düzeyleri
  • Derecelendirme aralıkları

Gerekli parametreler

Bu bölümde, Places Aggregate API'ye istek gönderirken gereken parametreler ele alınmaktadır. Her istekte aşağıdakiler sağlanmalıdır:

• Bir analiz türü.
• Konum filtresi ve tür filtresi.

Analiz türü

Hesaplamak istediğiniz analiz türünü belirtir. Aşağıdaki analiz türleri desteklenir:

• INSIGHT_COUNT: Filtre ölçütleriyle eşleşen yerlerin sayısını döndürür.
• INSIGHT_PLACES: Filtre ölçütleriyle eşleşen yer kimliklerini döndürür.

Not: INSIGHT_PLACES seçeneğini belirlerseniz Places Aggregate API, yalnızca count 100 veya daha azsa yer kimliklerini döndürür.

Filtreler

Yerler için filtreleme ölçütlerini belirtir. En azından LocationFilter ve TypeFilter değerlerini belirtmeniz gerekir.

Yer filtresi

Konum filtresi aşağıdaki türlerden birine sahip olabilir:

• circle: Bir alanı, merkezi ve yarıçapı olan bir daire olarak tanımlar.
• region: Bir alanı bölge olarak tanımlar.
• customArea: Bir alanı özel poligon olarak tanımlar.

Önemli: Konum filtrelerinin alanı 1.556,86 metrekare (yaklaşık olarak küçük bir şehir bloğu büyüklüğünde) ile 2 trilyon metrekare (yaklaşık olarak Alaska büyüklüğünde) arasında olmalıdır. Bu aralığın dışında alanlar içeren istekler INVALID_ARGUMENT hatası döndürür.

Not: Parklar veya havaalanları gibi tanımlanmış çokgen sınırları olan varlıklar için, çokgenin herhangi bir kısmı tanımlanan arama alanıyla (daire, bölge veya özel çokgen) kesişiyorsa varlık arama alanının içinde kabul edilir. Öğenin merkez noktasının arama alanında olması gerekmez.

Daire

Coğrafi bölgenizi daire olarak seçerseniz center ve radius belirtmeniz gerekir. center, enlem ve boylam ya da dairenin merkezinin yer kimliği olabilir. Bu yöntem, tanımladığınız dairesel bölgeye göre hassas ve doğru filtreleme yapmanıza olanak tanır.

• center:
  • latLng: Dairenin merkezinin enlem ve boylamı. Enlemler, -90 ile 90 arasında (bu değerler dahil) bir sayı olmalıdır. Boylam, -180 ile 180 arasında (değerler dahil) bir sayı olmalıdır.
  • place: Dairenin merkezinin yer kimliği. Yalnızca nokta yerlerin desteklendiğini unutmayın. Bu dize places/ önekiyle başlamalıdır.
• radius: Metre cinsinden dairenin yarıçapı. Bu sayı pozitif olmalıdır.

Bölge

place parametresine bir yer kimliği ileterek bölgenizi tanımlayın. Yer kimliği, coğrafi bir alanı (ör. çokgenle temsil edilebilen bir alan) temsil eder. Örneğin, Tampa, FL'nin yer kimliği places/ChIJ4dG5s4K3wogRY7SWr4kTX6c şeklindedir. Tüm yer kimliklerinin iyi tanımlanmış bir geometrisi olmadığını ve bu durumlarda Places Aggregate API'nin, bölgenin desteklenmediğini belirten bir mesajla birlikte 400 hata kodu döndürdüğünü unutmayın. Ayrıca, karmaşık coğrafi bölgeler için dahili işleme optimizasyonları, bölgeyi temsil eden alanın biraz fazla tahmin edilmesine (%2-3'e kadar) neden olabilir.

Önemli: region filtresini INSIGHT_PLACES analiz türüyle kullanırken, Google hizmetlerinin doğruluğunu ve tarafsızlığını sağlamak için ihtilaflı alanları içeren istekler otomatik olarak reddedilir. Anlaşmazlık bulunan bölgeler, farklı ülkeler veya tüzel kişiler tarafından sınırları ya da toprakları üzerinde hak iddia edilen bölgelerdir. İhtilaflı sınırlar, Google Haritalar'da kesik gri çizgiyle gösterilir.

Tartışmalı bölgelerin nasıl tanımlandığı hakkında daha fazla bilgi için Ülke sınırlarını ve adlarını anlama başlıklı makaleyi inceleyin.

Önemli: Google, aşağıdaki bölge türlerine ait belirli yer kimliklerini desteklemez:

• Yüksek gecikmeye neden olacak kadar büyük bölge türleri.
• Gizlilik kurallarına uygunluğu tehlikeye atacak kadar küçük olan bölge türleri.

Bir yer kimliğinin desteklenmeyen bir yer türünü temsil edip etmediğini belirlemek için yer kimliğini bir Geocoding API isteğine iletin. Yanıtta, yer kimliğiyle ilişkili yer türlerini (ör. locality, neighborhood veya country) listeleyen type dizisi yer alır. Türlerinden herhangi biri bu listeyle eşleşirse yer, bölge filtreleme için reddedilir.

Desteklenmeyen yer türleri şunlardır:

• establishment: Genellikle henüz kategorize edilmemiş bir yeri gösterir.
• intersection: Genellikle iki ana yolun kesiştiği büyük bir kavşağı gösterir.
• subpremise: Tesis düzeyinin altında, adreslenebilir bir varlığı (ör. apartman dairesi, birim veya süit) belirtir.

Not: Yukarıda listelenmeyen bazı yerler bile iyi tanımlanmış bir poligon geometrisine sahip değilse reddedilebilir. Bu durum, neighborhood, locality, sublocality ve numaralı varyantları (sublocality_level_1, sublocality_level_2, sublocality_level_3, sublocality_level_4) gibi türlerde daha yaygındır. Bu durumda 400 hata kodu döndürülür.

Özel alan

Enlem ve boylam koordinatlarını kullanarak özel bir poligonun alanını tanımlar.

Önemli: Çokgenin köşelerini tanımlayan koordinatlar, saat yönünün tersine doğru sıralanmalıdır. Bu, çokgenleri tanımlamak için kullanılan endüstri standardı kuralına uygundur. Bu kuralda, saat yönünün tersi, çokgenin iç kısmının sınır kenarlarının solunda olduğunu gösterir.

Önemli: Özel alanlarda en fazla 7.000 köşe bulunmalıdır.

Özel bir çokgen çizmek ve bu koordinatları isteğe girmek için https://geojson.io/ adresini ziyaret edebilirsiniz. Poligon en az 4 koordinata sahip olmalıdır. İlk ve son koordinatlar aynı olmalıdır. Sağlanan koordinatlardan en az 3'ü benzersiz olmalıdır.

Birbirini takip eden aynı koordinatlar tek bir koordinat olarak değerlendirilir. Ancak, ardışık olmayan yinelenen koordinatlar (gerekli olan aynı ilk ve son koordinatlar dışında) hataya neden olur.

Ayrıca, bitişik olmayan kenarların kesişmesine izin verilmez ve 180 derece uzunluğundaki kenarlara izin verilmez (yani bitişik köşeler antipodal olamaz).

Örneğin:

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

Tür filtresi

Dahil edilecek veya hariç tutulacak yer türlerini belirtir. Places Aggregate API'nin desteklediği birincil ve ikincil yer türlerinin listesi için Places API (Yeni) ile ilgili Yer Türleri bölümündeki Tablo A'ya bakın. En az bir includedTypes veya includedPrimaryTypes türü belirtmeniz gerekir.

• includedTypes: Dahil edilen yer türlerinin listesi.
• excludedTypes: Hariç tutulan yer türlerinin listesi.
• includedPrimaryTypes: Dahil edilen birincil yer türlerinin listesi.
• excludedPrimaryTypes: Hariç tutulan birincil yer türlerinin listesi.

Tür filtrelerinin ve yer türlerinin işleyiş şekli hakkında daha fazla bilgi edinmek için tür filtreleri hakkında daha fazla bilgi başlıklı makaleyi inceleyin.

Not: Tür filtreleri, belirtilen türlerin alt türlerini otomatik olarak içerir. Örneğin, gym türüne göre filtreleme yaparsanız sonuçlara yoga_studio gibi alt türleri altında kategorize edilen yerler de dahil edilir.

İsteğe bağlı parametreler

Bu filtreler isteğe bağlıdır:

• operatingStatus: Dahil edilecek veya hariç tutulacak yerlerin durumlarını belirtir. Varsayılan olarak operatingStatus: OPERATING_STATUS_OPERATIONAL (belirli bir değer) ölçütüne göre filtreleme yapılır.
• priceLevels: Dahil edilecek yerlerin fiyat seviyelerini belirtir. Varsayılan olarak, fiyat seviyesi filtrelemesi uygulanmaz ve tüm yerler (fiyat seviyesi bilgisi olmayanlar dahil) döndürülür.
• ratingFilter: Yerlerin puan aralığını belirtir. Varsayılan olarak filtreleme yapılmaz (tüm puanlar sonuçlara dahil edilir).

Faaliyet durumu

operatingStatus filtresiyle, OPERATIONAL veya TEMPORARILY_CLOSED gibi faaliyet durumuna göre filtreleme yapabilirsiniz. operatingStatus filtresinin davranışı şu şekildedir:

• Filtre sağlanmadıysa sonuçlara yalnızca faaliyet durumu OPERATING_STATUS_OPERATIONAL olan yerler dahil edilir.
• Bir veya daha fazla filtre sağlanırsa geçerli faaliyet durumu değerlerini (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED veya OPERATING_STATUS_TEMPORARILY_CLOSED) belirtmeniz gerekir.

Fiyat düzeyi

priceLevels filtresiyle yerleri fiyat düzeyine göre filtreleyebilirsiniz. Geçerli fiyat düzeyi değerleri: PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE ve PRICE_LEVEL_VERY_EXPENSIVE.

priceLevels filtresinin davranışı aşağıdaki gibidir:

• Filtre sağlanmazsa: Fiyat seviyesi atanıp atanmadığına bakılmaksızın tüm yerler döndürülür. Fiyat düzeyi bilgisi olmayan yerler de buna dahildir. Bu yerler, belirli fiyat düzeylerine göre filtreleme yapıldığında döndürülmeyebilir.
• Bir veya daha fazla filtre sağlanırsa: Yalnızca belirtilen fiyat seviyeleriyle eşleşen yerler döndürülür.

Puan filtresi

Yerler, ortalama kullanıcı puanlarına göre filtrelenir. Bu alanların ikisi de isteğe bağlıdır. Bu nedenle, atlanırlarsa varsayılan olarak puanı olmayan yerleri de dahil ederler.

• minRating: Minimum ortalama kullanıcı puanı (1,0 ile 5,0 arasında).
• maxRating: Maksimum ortalama kullanıcı puanı (1,0 ile 5,0 arasında).

Ayrıca, minRating değeri her zaman maxRating değerinden küçük veya bu değere eşit olmalıdır. minRating, maxRating değerinden büyük olarak belirtilirse INVALID_ARGUMENT hatası döndürülür.