Yakında Arama (Yeni) isteği bir veya daha fazla yer türü alır ve belirtilen bölgedeki eşleşen yerlerin bir listesini döndürür. Bir veya daha fazla veri türü belirten bir alan maskesi gereklidir. Yakındaki Arama (Yeni) yalnızca POST isteklerini destekler.
API Explorer, API ve API seçenekleri hakkında bilgi edinebilmeniz için canlı istekler yapmanıza olanak tanır:
Deneyin.Yakındaki Arama (Yeni) sonuçlarını haritada görmek için etkileşimli demoyu deneyin.
Yakındaki Arama (Yeni) istekleri
Yakındaki Arama (Yeni) isteği, formdaki bir URL'ye yapılan HTTP POST isteğidir:
https://places.googleapis.com/v1/places:searchNearby
JSON isteği gövdesindeki veya başlıklardaki tüm parametreleri, POST isteğinin bir parçası olarak 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ındaki 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
nesnesiyle temsil edilir.Place
nesnesi, tek bir yer hakkında ayrıntılı bilgiler içerir. - İstekte iletilen FieldMask,
Place
nesnesinde döndürülen alanların listesini belirtir.
JSON nesnesinin tamamı aşağıdaki biçimdedir:
{ "places": [ { object (Place) } ] }
Gerekli parametreler
-
FieldMask
Yanıt alanı maskesi oluşturarak yanıtta döndürülecek alanların listesini belirtin.
$fields
veyafields
URL parametresini ya daX-Goog-FieldMask
HTTP üst bilgisini kullanarak yanıt alanı maskesini yönteme iletin. Yanıtta varsayılan bir döndürülen alan listesi yok. Alan maskesini çıkarırsanız yöntem hata döndürür.Alan maskeleme, gereksiz veri isteğinde bulunmadığınızdan emin olmak için iyi bir tasarım uygulamasıdır. Bu da gereksiz işleme süresi ve faturalandırma ücretlerinin önlenmesine yardımcı olur.
Döndürülecek yer verisi türlerinin virgülle ayrılmış listesini belirtin. Örneğin, yerin görünen adını ve adresini almak için.
X-Goog-FieldMask: places.displayName,places.formattedAddress
Tüm alanları almak için
*
öğesini kullanın.X-Goog-FieldMask: *
Aşağıdaki alanlardan birini veya daha fazlasını belirtin:
Aşağıdaki alanlar Yakındaki Arama (Temel) SKU'sunu tetikler:
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.attributions
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
içindeplaces.primaryTypeDisplayName
,places.subDestinations
,places.subDestinations
,places.subDestinations
,places.subDestinations
biçimindeplaces.subDestinations
,places.subDestinations
,places.subDestinations
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
places.name
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
Yerin metin adına erişmek içinplaces.displayName
kullanın.Aşağıdaki alanlar Yakında Arama (Gelişmiş) SKU'sunu tetikler:
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,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.servesBeer
,places.servesBrunch
, {29,places.servesBeer
,places.servesBeer
places.servesBreakfast
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
Merkez noktası ve metre cinsinden yarıçapla tanımlanan, çember şeklinde belirtilen, aranacak bölge. Yarıçap, 0,0 ile 50.000,0 (her ikisi de dahil) arasında 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
-
includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
Arama sonuçlarını filtrelemek için kullanılan Tablo A türlerinden bir tür listesi belirtebilmenizi sağlar. Her bir tür kısıtlama kategorisinde en fazla 50 tür belirtilebilir.
Bir yerin kendisiyle ilişkili tek bir birincil türü olabilir Tablo A. Örneğin, birincil tür
"mexican_restaurant"
veya"steak_house"
olabilir. Sonuçları bir yerin birincil türüne göre filtrelemek içinincludedPrimaryTypes
veexcludedPrimaryTypes
özelliklerini kullanın.Bir yer, kendisiyle ilişkili Tablo A türlerinden birden fazla tür değere sahip olabilir. Örneğin bir restoran şu türlere sahip olabilir:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. Bir yerle ilişkili türler listesindeki sonuçları filtrelemek içinincludedTypes
veexcludedTypes
özelliklerini kullanın.Bir arama birden çok tür kısıtlamasıyla belirtilirse yalnızca tüm kısıtlamaları karşılayan yerler döndürülür. Örneğin,
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
özelliğini belirtirseniz döndürülen yerler"restaurant"
ile ilgili hizmetler sağlar ancak birincil olarak"steak_house"
olarak çalışmaz.includedTypes
Tablo A'dan aranacak yer türlerinin virgülle ayrılmış listesi. Bu parametre eklenmezse her türden yer döndürülür.
excludedTypes
Aramadan hariç tutulacak Tablo A'daki yer türlerinin virgülle ayrılmış listesi.
İstekte hem
includedTypes
("school"
gibi) hem deexcludedTypes
("primary_school"
gibi) değerini belirtirseniz yanıt,"school"
olarak sınıflandırılan ancak"primary_school"
olarak kategorize edilmeyen yerleri içerir. Yanıt,includedTypes
özelliklerinden en az biriyle eşleşen veexcludedTypes
hiçbiriyle eşleşen yerleri içerir.Çakışan türler varsa (ör. hem
includedTypes
hem deexcludedTypes
'da görünen bir tür)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 Tablo A'daki birincil yer türlerinin virgülle ayrılmış listesi.
Hem
includedPrimaryTypes
hem deexcludedPrimaryTypes
içinde görünen bir tür gibi çakışan birincil türler varsaINVALID_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 kapsamlı olmayabilir.
languageCode
sağlanmazsa API varsayılan olaraken
olur. Geçersiz bir dil kodu belirtirseniz API,INVALID_ARGUMENT
hatası döndürür.- API, hem kullanıcı hem de bölge sakinlerinin okuyabileceği bir açık adres sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için yerel dildeki açık adresleri, gerekirse kullanıcı tarafından okunabilecek bir alfabeye dönüştürülerek tercih edilen dile uyarlar. 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.
- Bir ad, tercih edilen dilde sunulmuyorsa API en yakın eşleşmeyi kullanır.
- Tercih edilen dilin, API'nin döndürmeyi seçtiği sonuç kümesi ve döndürülme sırası üzerinde küçük bir etkisi vardır. Coğrafi kodlayıcı, kısaltmaları dile bağlı olarak farklı şekilde yorumlar. Örneğin, sokak türlerinin kısaltmaları ya da bir dilde geçerli olup başka bir dilde geçerli olmayan eş anlamlı kelimeler olabilir.
-
maxResultCount
Döndürülecek maksimum yer sonucu sayısını belirtir. 1-20 (varsayılan) dahil bu değerler arasında olmalıdır.
-
rankPreference
Kullanılacak sıralama türü. Bu parametre eklenmezse 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 bir değer yok.
Yanıttaki
formattedAddress
alanının ülke adıregionCode
ile eşleşirse ülke koduformattedAddress
öğesinden çıkarılır. Bu parametrenin, her zaman ülke adını içerenadrFormatAddress
veya hiçbir zaman içermeyenshortFormattedAddress
üzerinde etkisi yoktur.Çoğu CLDR kodu, 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), ISO 3166-1 kodu "gb" (teknik olarak "Büyük Britanya ve Kuzey İrlanda'daki Birleşik Krallık'a" ait tüzel kişi için) "gb" şeklindedir. Parametre, geçerli yasalara göre sonuçları etkileyebilir.
Yakındaki Arama (Yeni) örnekleri
Belirli türdeki yerleri bulma
Aşağıdaki örnekte, 500 metrelik yarıçap içindeki tüm restoranların görünen adları için circle
tarafından tanımlanan 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
üstbilgisinin, yanıtın şu veri alanlarını içerdiğini belirttiğini unutmayın: places.displayName
.
Bu durumda yanıt şu biçimde olur:
{ "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, yanıta restoranın adresini, türünü ve web adresini 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 şu biçimde:
{ "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" } }, ... }
Farklı türde yerler bulun
Aşağıdaki örnekte, belirtilen circle
bölgesinin 1.000 metrelik yarıçapı dahilindeki tüm marketlerin ve içki mağazalarının görünen adları için Yakınlarda Arama (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:searchNearbyBu örnekte, alan maskesine
places.primaryType
ve places.types
eklenerek yanıtın her bir yer hakkında tür bilgisi içermesi, sonuçlardan uygun yerin seçilmesini kolaylaştırır.
Bir yer türünü aramadan hariç tutma
Aşağıdaki örnekte "school"
türündeki tüm yerler için Yakındaki Arama (Yeni) isteği gösterilmektedir. "primary_school"
türündeki tüm yerler hariç tutularak 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 arama (mesafeye göre sıralama)
Aşağıdaki örnekte, San Francisco şehir merkezinde bir noktanın yakınındaki yerler için Yakınlarda Arama (Yeni) isteği gösterilmektedir. Bu örnekte, sonuçları mesafeye 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 ve API seçeneklerini tanıyabilmeniz için örnek isteklerde bulunmanıza olanak tanır.
- Sayfanın sağ tarafındaki API simgesini () seçin.
- İsteğe bağlı olarak Standart parametreleri göster seçeneğini genişletin ve
fields
parametresini alan maskesi olarak ayarlayın. - İsteğe bağlı olarak İstek gövdesini düzenleyin.
- Yürüt düğmesini seçin. Pop-up pencerede, istekte bulunmak için kullanmak istediğiniz hesabı seçin.
API Gezgini panelinde genişletme simgesini () seçerek API Gezgini penceresini genişletin.