Yakında Arama (Yeni)

Yakındakiler Arama (Yeni) isteği, bir veya daha fazla yer türünü alır ve belirtilen alanda eşleşen yerlerin listesini döndürür. Bir veya daha fazla veri türünü belirten bir alan maskesi gereklidir. Yakındakiler araması (yeni) yalnızca POST isteklerini destekler.

API Gezgini, API'ye ve API seçeneklerine aşina olabilmeniz için canlı istek göndermenize olanak tanır:

Yakındakiler Arama (Yeni) sonuçlarını haritada görmek için etkileşimli demoyu deneyin.

Yakında Arama (Yeni) istekleri

Yakındakiler araması (yeni) isteği, aşağıdaki biçimdeki bir URL'ye gönderilen bir HTTP POST isteğidir:

https://places.googleapis.com/v1/places:searchNearby

Tüm parametreleri JSON istek gövdesinde veya POST isteğinin bir parçası olarak üstbilgilerde iletin. Örneğin:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Yakında Arama (Yeni) yanıtları

Yakındaki Arama (Yeni), yanıt olarak bir JSON nesnesi döndürür. Yanıtta:

• places dizisi, eşleşen tüm yerleri içerir.
• Dizideki her yer bir Place nesnesi ile temsil edilir. Place nesnesi, tek bir yerle ilgili ayrıntılı bilgileri içerir.
• İstekte iletilen FieldMask, Place nesnesinde döndürülen alanların listesini belirtir.

JSON nesnesinin tamamı şu şekildedir:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Gerekli parametreler

• FieldMask

  Yanıt alanı maskesi oluşturarak yanıtta döndürülecek alanların listesini belirtin. Yanıt alan maskesini, URL parametresi $fields veya fields'yi ya da HTTP üst bilgisi X-Goog-FieldMask'yi kullanarak yönteme iletin. Yanıtta döndürülen alanların varsayılan listesi yoktur. Alan maskesini atlarsanız yöntem bir hata döndürür.

  Alan maskeleme, gereksiz veri istememenizi sağlamak için iyi bir tasarım uygulamasıdır. Bu uygulama, gereksiz işlem süresinden ve faturalandırma ücretlerinden kaçınmanıza yardımcı olur.

  Döndürülecek yer veri türlerinin virgülle ayrılmış bir listesini belirtin. Örneğin, bir yerin görünen adını ve adresini almak için

  X-Goog-FieldMask: places.displayName,places.formattedAddress

  Tüm alanları almak için * değerini kullanın.

  X-Goog-FieldMask: *

  Aşağıdaki alanlardan en az birini belirtin:

  • Aşağıdaki alanlar Yakındakiler Arama (Temel) SKU'sunu tetikler:

    places.accessibilityOptions
places.addressComponents
places.adrFormatAddress
places.attributions
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks^*
    places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.id
places.location
places.name^**
    places.photos
places.plusCode
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
    
    ^* places.googleMapsLinks alanı GA öncesi önizleme aşamasındadır ve önizleme sırasındaki kullanım için ücret alınmaz. Yani faturalandırma 0 ABD dolarıdır.
    
    ^** places.name alanı, places/PLACE_ID biçiminde kaynak adını içerir. Yerin metin adına erişmek için places.displayName kullanın.

  • Aşağıdaki alanlar Yakındakiler Arama (Gelişmiş) SKU'sunu tetikler:

    places.currentOpeningHours
places.currentSecondaryOpeningHours
places.internationalPhoneNumber
places.nationalPhoneNumber
places.priceLevel
places.priceRange
places.rating
places.regularOpeningHours
places.regularSecondaryOpeningHours
places.userRatingCount
places.websiteUri

  • Aşağıdaki alanlar Yakındaki Arama (Tercih Edilen) SKU'sunu tetikler:

    places.allowsDogs
places.curbsidePickup
places.delivery
places.dineIn
places.editorialSummary
places.evChargeOptions
places.fuelOptions
places.goodForChildren
places.goodForGroups
places.goodForWatchingSports
places.liveMusic
places.menuForChildren
places.parkingOptions
places.paymentOptions
places.outdoorSeating
places.reservable
places.restroom
places.reviews
places.routingSummaries^*
    places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
    
    ^* Yalnızca metin arama ve yakınlardakiler

• locationRestriction

  Merkez noktası ve yarıçapı metre cinsinden tanımlanan, daire olarak belirtilen arama bölgesi. Yarıçap 0,0 ile 50000,0 arasında (bu değerler dahil) olmalıdır. Varsayılan yarıçap 0,0'dır. İsteğinizde bu değeri 0,0'dan büyük bir değere ayarlamanız gerekir.

  Örneğin:

  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }

İsteğe bağlı parametreler

• includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

  Arama sonuçlarını filtrelemek için kullanılan Tablo A türlerinden türlerin listesini belirtmenizi sağlar. Her tür kısıtlama kategorisinde en fazla 50 tür belirtilebilir.

  Bir mekan, kendisiyle ilişkili Tablo A türlerinden yalnızca tek bir birincil türe sahip olabilir. Örneğin, birincil tür "mexican_restaurant" veya "steak_house" olabilir. Sonuçları bir yerin birincil türüne göre filtrelemek için includedPrimaryTypes ve excludedPrimaryTypes değerlerini kullanın.

  Bir yerin, ilişkili Tablo A türlerinden birden fazla tür değeri de olabilir. Örneğin, bir restoranın şu türleri olabilir: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Bir yerle ilişkili türlerin listesindeki sonuçları filtrelemek için includedTypes ve excludedTypes tuşlarını kullanın.

  "restaurant" veya "hotel" gibi genel bir birincil tür belirttiğinizde yanıt, belirtilenden daha spesifik birincil türde yerler içerebilir. Örneğin, birincil tür olarak "restaurant" eklemeyi belirtirsiniz. Yanıt, birincil türü "restaurant" olan yerleri içerebilir ancak "chinese_restaurant" veya "seafood_restaurant" gibi daha spesifik birincil türe sahip yerleri de içerebilir.

  Birden fazla tür kısıtlaması içeren bir arama yapılırsa yalnızca tüm kısıtlamaları karşılayan yerler döndürülür. Örneğin, {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} değerini belirtirseniz döndürülen yerler "restaurant" ile ilgili hizmetler sunar ancak birincil olarak "steak_house" olarak faaliyet göstermez.

  includedTypes

  A Tablosu'ndaki aranacak yer türlerinin virgülle ayrılmış listesi. Bu parametre atlanırsa tüm türde yerler döndürülür.

  excludedTypes

  Aramadan hariç tutulacak Tablo A'daki yer türlerinin virgülle ayrılmış listesi.

  İstekte hem includedTypes ( ör. "school") hem de excludedTypes (ör. "primary_school") parametresini belirtirseniz yanıt, "school" olarak sınıflandırılan ancak "primary_school" olarak sınıflandırılmayan yerleri içerir. Yanıt, includedTypes ile en az bir, excludedTypes ile ise hiçbir eşleşmeyen yerleri içeriyor.

  Hem includedTypes hem de excludedTypes'te görünen bir tür gibi çelişen tür varsa INVALID_REQUEST hatası döndürülür.

  includedPrimaryTypes

  Aramaya dahil edilecek Tablo A'daki birincil yer türlerinin virgülle ayrılmış listesi.

  excludedPrimaryTypes

  Aramadan hariç tutulacak A Tablosu'ndaki birincil yer türlerinin virgülle ayrılmış listesi.

  Hem includedPrimaryTypes hem de excludedPrimaryTypes'te görünen bir tür gibi birbiriyle çelişen birincil türler varsa INVALID_ARGUMENT hatası döndürülür.

• languageCode

  Sonuçların döndürüleceği dil.

  • Desteklenen dillerin listesini inceleyin. Google, desteklenen dilleri sık sık güncellediğinden bu liste tam olmayabilir.
  • languageCode sağlanmazsa API varsayılan olarak en değerini kullanır. Geçersiz bir dil kodu belirtirseniz API INVALID_ARGUMENT hatası döndürür.
  • API, hem kullanıcı hem de yerel halk tarafından okunabilen bir açık adres sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için sokak adreslerini yerel dilde döndürür. Gerekirse tercih edilen dile göre, kullanıcı tarafından okunabilir bir yazım sistemine dönüştürülür. Diğer tüm adresler tercih edilen dilde döndürülür. Adres bileşenlerinin tümü, ilk bileşenden seçilen aynı dilde döndürülür.
  • Tercih edilen dilde bulunmayan bir ad varsa API en yakın eşlemeyi kullanır.
  • Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç grubu ve bu sonuçların döndürülme sırası üzerinde küçük bir etkiye sahiptir. Coğrafi kodlayıcı, kısaltmaları dile göre farklı şekilde yorumlar. Örneğin, sokak türlerinin kısaltmaları veya bir dilde geçerli olup başka bir dilde geçerli olmayan eş anlamlılar.

• maxResultCount

  Döndürülecek maksimum yer sonucu sayısını belirtir. 1 ile 20 (varsayılan) arasında olmalıdır.

• rankPreference

  Kullanılacak sıralama türü. Bu parametre atlanırsa sonuçlar popülerliğe göre sıralanır. Aşağıdakilerden biri olabilir:

  • POPULARITY (varsayılan) Sonuçları popülerliklerine göre sıralar.
  • DISTANCE Sonuçları, belirtilen konuma olan mesafelerine göre artan düzende sıralar.

• regionCode

  Yanıtı biçimlendirmek için kullanılan bölge kodu. İki karakterli CLDR kodu değeri olarak belirtilir. Varsayılan değer yoktur.

  Yanıttaki formattedAddress alanının ülke adı regionCode ile eşleşirse ülke kodu formattedAddress'ten çıkarılır. Bu parametrenin, ülke adını her zaman içeren adrFormatAddress veya ülke adını hiçbir zaman içermeyen shortFormattedAddress üzerinde etkisi yoktur.

  CLDR kodlarının çoğu, 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) iken 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.

Yakında Arama (Yeni) örnekleri

Aynı türden yerleri bulma

Aşağıdaki örnekte, circle tarafından tanımlanan 500 metre yarıçapındaki tüm restoranların görünen adları için bir Yakındaki Arama (Yeni) isteği gösterilmektedir:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

X-Goog-FieldMask başlığının, yanıtın aşağıdaki veri alanlarını içerdiğini belirttiğini unutmayın: places.displayName. Yanıt şu şekildedir:

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

Ek bilgiler döndürmek için alan maskesine daha fazla veri türü ekleyin. Örneğin, restoran adresini, türünü ve web adresini yanıta dahil etmek için places.formattedAddress,places.types,places.websiteUri ekleyin:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

Yanıt artık formdadır:

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

Birden fazla türde yer bulma

Aşağıdaki örnekte, belirtilen circle noktasının 1.000 metre yarıçapındaki tüm marketlerin ve içki mağazalarının görünen adları için bir Yakındakileri Ara (Yeni) isteği gösterilmektedir:

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby

Bir yer türünü aramadan hariç tutma

Aşağıdaki örnekte, "primary_school" türündeki tüm yerler hariç "school" türündeki tüm yerler için bir Yakındakiler Arama (Yeni) isteği gösterilmektedir. Sonuçlar mesafeye göre sıralanmıştır:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Bir bölgenin yakınındaki tüm yerleri mesafeye göre sıralayarak arama

Aşağıdaki örnekte, San Francisco şehir merkezindeki bir noktanın yakınındaki yerler için Yakındakileri Ara (Yeni) isteği gösterilmektedir. Bu örnekte, sonuçları uzaklığa göre sıralamak için rankPreference parametresini eklersiniz:

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Deneyin!

API Gezgini, API'ye ve API seçeneklerine aşina olabilmeniz için örnek istekler göndermenize olanak tanır.

1. Sayfanın sağ tarafındaki API simgesini api seçin.

2. İsteğe bağlı olarak istek parametrelerini düzenleyin.

3. Yürüt düğmesini seçin. İletişim kutusunda, isteği göndermek için kullanmak istediğiniz hesabı seçin.

4. API Gezgini panelinde, API Gezgini penceresini genişletmek için tam ekran simgesini tam ekran seçin.