İstek parametreleri

Bu belgede, Places Aggregate API'nin istek parametreleri açıklanmakta ve bu hizmetin kullanımına ilişkin analizler ile en iyi uygulamalar yer almaktadır.

Places Aggregate API, çeşitli temel işlevleri gerçekleştirmenize olanak tanır:

• Yerleri sayma: Konum türü, çalışma durumu, fiyat düzeyi ve kullanıcı oyları gibi belirli ölçütlere uyan yerlerin sayısını belirleyin.
• Yer ayrıntılarını alma: Belirtilen filtrelere uyan yerlerin adlarını alın, ardından Places API'yi kullanarak daha ayrıntılı bilgiler getirin.
• Esnek filtreleme: Kesin 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 gerekli olan 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: Filtreleme ölçütleriyle eşleşen yer kimliklerini döndürür.

Filtreler

Yerleri filtreleme ölçütlerini belirtir. En azından LocationFilter ve TypeFilter özelliklerini belirtmeniz gerekir.

Yer filtresi

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

• circle: Bir alanı merkez 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.

Daire

Coğrafi bölgenizi daire olarak seçerseniz center ve radius sağlamanız gerekir. center, enlem ve boylam veya dairenin merkezinin yer kimliği olabilir. Bu yöntem, tanımladığınız dairesel bölgeye göre hassas ve doğru filtreleme yapılmasını sağlar.

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

Bölge

place parametresine bir yer kimliği ileterek bölgenizi bir bölge olarak tanımlayın. Yer kimliği, coğrafi bir alanı (ör. bir poligonla gösterilebilen bir alan) temsil eder. Örneğin, Tampa, Florida'nın yer kimliği places/ChIJ4dG5s4K3wogRY7SWr4kTX6c'dır. Tüm yer kimliklerinin iyi tanımlanmış bir geometriye sahip 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ölgelerde dahili işleme optimizasyonları, bölgeyi temsil eden alanın biraz fazla tahmin edilmesine (en fazla %2-3) neden olabilir.

Bir yer kimliğinin desteklenmeyen bir yer türünü temsil edip etmediğini belirlemek için yer kimliğini Geocoding API isteğinde 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ındaki adreslenebilir bir varlığı (ör. daire, birim veya süit) gösterir.

Özel alan

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

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

Ardı sıra gelen aynı koordinatlar tek bir koordinat olarak değerlendirilir. Ancak, ardışık olmayan yinelenen koordinatlar (gerekli olan aynı ilk ve son koordinatlar hariç) hataya neden olur.

Ayrıca, bitişik olmayan kenarların kesişmesine 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 hem birincil hem de ikincil yer türlerinin listesi için Places API (Yeni) Yer Türleri bölümündeki Tablo A'ya bakın. En az bir includedTypes veya includedPrimaryTypes türü belirtmelisiniz.

• 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.

İ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) sütununa göre filtreleme yapılır.
• priceLevels: Dahil edilecek yerlerin fiyat düzeylerini belirtir. Varsayılan olarak, fiyat düzeyi filtreleme uygulanmaz ve fiyat düzeyi bilgisi olmayanlar da dahil olmak üzere tüm yerler döndürülür.
• ratingFilter: Yerlerin puan aralığını belirtir. Varsayılan olarak filtreleme yapılmaz (tüm derecelendirmeler sonuçlara dahil edilir).

Faaliyet durumu

operatingStatus filtresiyle OPERATIONAL veya TEMPORARILY_CLOSED gibi Çalışma Durumu'na göre filtreleme yapabilirsiniz. operatingStatus filtre davranışının işleyiş şekli şöyledir:

• Filtre sağlanmadıysa sonuçlara yalnızca OPERATING_STATUS_OPERATIONAL çalışma durumuna sahip yerler dahil edilir.
• Bir veya daha fazla filtre sağlanıyorsa geçerli çalışma 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üzeylerine göre filtreleyebilirsiniz. Geçerli fiyat düzeyi değerleri şunlardır: 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 düzeyi atanmış olup olmadığı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 düzeyleriyle eşleşen yerler döndürülür.

Puan filtresi

Yerleri ortalama kullanıcı puanlarına göre filtreler. Bu alanların her ikisi de isteğe bağlıdır. Bu nedenle, atlanmaları durumunda derecelendirmesi olmayan yerler de varsayılan olarak dahil edilir.

• 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 ona eşit olmalıdır. minRating, maxRating değerinden büyük olarak belirtilirse INVALID_ARGUMENT hatası döndürülür.