İstek parametreleri

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

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

• Yerleri sayma: Konum türü, çalışma durumu, fiyat seviyesi 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 analizler 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 Insights API'ye istek gönderirken gerekli olan parametreler açıklanmaktadır. Her istek şunları sağlamalıdır:

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

Analiz türü

Hesaplamak istediğiniz analizlerin 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.

Filtreler

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

Yer filtresi

Konum filtresi aşağıdaki türlerden biri 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.

Daire

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

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

Bölge

place parametresine bir yer kimliği göndererek bölgenizi bölge olarak tanımlayın. Yer kimliği, bir coğrafi alanı (ör. poligonla temsil edilebilen bir alan) temsil eder. Örneğin, Tampa, Florida'nın yer kimliği places/ChIJ4dG5s4K3wogRY7SWr4kTX6c'tür. Tüm yer kimliklerinin iyi tanımlanmış bir geometriye sahip olmadığını ve bu durumlarda Places Insights 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ı biraz fazla tahmin etmeye (%2-3'e kadar) neden olabilir.

Bir yer kimliğinin desteklenmeyen bir yer türünü temsil edip etmediğini belirlemek için yer kimliğini bir Coğrafi Kodlama API isteğinde iletin. Yanıtta, yer kimliğiyle ilişkili yer türlerini (ör. city, neighborhood veya country) listeleyen type dizisi yer alır.

Desteklenmeyen yer türleri şunlardır:

• establishment: Genellikle henüz kategorize edilmemiş bir yeri gösterir.
• street_number: Tam sokak numarasını belirtir.
• floor: Bina adresinin katını belirtir.
• post_box: Belirli bir posta kutusunu belirtir.
• street_address: Tam açık adresi belirtir.
• room: Bir bina adresinin odasını belirtir.
• intersection: Genellikle iki ana yolun kesiştiği önemli bir kavşağı belirtir.
• landmark: Gezinmeye yardımcı olmak için referans olarak kullanılan yakın bir yeri gösterir.
• subpremise: Tesis seviyesinin altındaki adreslenebilir bir varlığı (ör. daire, birim veya süit) gösterir.
• sublocality_level_5: Alt mahalle adres bileşenlerinin en ayrıntılı düzeyi. Genellikle bir şehirdeki çok küçük bir mahalle alt bölümünü veya hiper yerel bir alanı temsil eder.

Özel alan

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

Özel bir poligon ç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 koordinatların ilk ve sonu aynı olmalıdır. Sağlanan koordinatlardan en az 3'ü benzersiz olmalıdır.

Ardışık olarak aynı koordinatlar tek bir koordinat olarak değerlendirilir. Ancak art arda olmayan yinelenen koordinatlar (zorunlu olarak aynı olan 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 zıt 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 Insights 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ü 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.

İ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 değerine (belirli bir değer) göre filtreleme yapar.
• priceLevels: Yerlerin fiyat düzeylerini belirtir. Varsayılan olarak filtreleme yapılmaz (tüm fiyat seviyeleri sonuçlara dahil edilir).
• ratingFilter: Yerlerin puan aralığını belirtir. Varsayılan olarak filtreleme yapılmaz (tüm derecelendirmeler sonuçlara dahil edilir).

Faaliyet durumu

operatingStatus filtresiyle Faaliyet Durumu'na (ör. faaliyette veya geçici olarak kapalı) göre filtreleme yapabilirsiniz. operatingStatus filtresi ayarlanmamışsa sonuçlara yalnızca OPERATING_STATUS_OPERATIONAL işletim durumu olan yerler dahil edilir.

Fiyat düzeyi

price_levels filtresiyle Fiyat Seviyesi'ne (ör. ücretsiz, orta veya pahalı) göre filtreleme yapabilirsiniz. price_levels filtresi ayarlanmazsa tüm fiyat seviyeleri sonuçlara dahil edilir.

Puan filtresi

Yerleri ortalama kullanıcı puanlarına göre filtreler. Bu iki alan da isteğe bağlıdır. Bu nedenle, atlanırlarsa varsayılan olarak puanı olmayan yerleri de içerirler.

• 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'ten büyük olarak belirtilirse INVALID_ARGUMENT hatası döndürülür.