Yakında Arama (Yeni) isteği bir veya daha fazla yer türünü alır ve belirtilen alandaki 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'yi ve API seçeneklerini tanımanız için canlı isteklerde bulunmanıza olanak tanır:
Deneyin.Yakındaki Arama (Yeni) istekleri
Yakındaki Arama (Yeni) isteği, aşağıdaki biçimdeki bir URL'ye yapılan 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 başlıklarda geçirin. Ö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çeriyor.- 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ı şu 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 döndürülen alanların varsayılan bir listesi yoktur. Alan maskesini çıkarırsanız yöntem bir 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. Böylece gereksiz işleme süresi ve faturalandırma ücretlerinin önüne geçilir.
Döndürülecek yer verisi türlerinin virgülle ayrılmış listesini belirtin. Örneğin, görünen adı ve yerin adresini alabilirsiniz.
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.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
, {2, , {2. , {18//}{18//}places.subDestinations
alanı {2. alanı,places.subDestinations
places.name
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
Yerin metin adına erişmek içinplaces.displayName
öğesini kullanın.Aşağıdaki alanlar Yakındaki 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.reservable
,places.restroom
places.reviews
,places.curbsidePickup
places.reviews
,places.curbsidePickup
places.reviews
places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
Merkez noktası ve yarıçapla tanımlanan, metre cinsinden daire olarak belirtilmiş, aranacak bölge. Yarıçap 0,0 ile 50000,0 (her ikisi de dahil) arasında olmalıdır. Varsayılan yarıçap 0,0'dır. Bu değeri isteğinizde 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
-
includes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
Arama sonuçlarını filtrelemek için kullanılan Tablo A türlerinden bir tür listesi belirtebilmenizi sağlar. Her tür kısıtlama kategorisinde en fazla 50 tür belirtilebilir.
Bir yerin yalnızca kendisiyle ilişkili Tablo A türlerindeki tek bir birincil türü olabilir. Ö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
öğelerini kullanın.Bir yerin kendisiyle ilişkili Tablo A türlerinden birden çok tür değeri de 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
kullanın.Bir arama birden fazla 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"]}
değerini belirtirseniz döndürülen yerler"restaurant"
ile ilgili hizmetler sağlar ancak esasen"steak_house"
olarak çalışmaz.includedTypes
A Tablosu'nda aranacak yer türlerinin virgülle ayrılmış listesi. Bu parametre atlanırsa, her türden yer döndürülür.
excludedTypes
Aramadan hariç tutmak için A Tablosu'ndaki yer türlerinin virgülle ayrılmış listesi.
İstekte hem
includedTypes
("school"
gibi) hem deexcludedTypes
("primary_school"
gibi) belirtirseniz yanıt,"school"
olarak sınıflandırılan ancak"primary_school"
olarak kategorize edilmeyen yerleri içerir. Yanıt,includedTypes
öğelerinden en az biriyle veexcludedTypes
öğelerinden hiçbiri ile eşleşen yerleri içerir.Hem
includedTypes
hem deexcludedTypes
içinde görünen bir tür gibi çakışan türler varsaINVALID_REQUEST
hatası döndürülür.includedPrimaryTypes
Bir aramaya dahil edilecek birincil yer türlerinin virgülle ayrılmış listesi A'dan.
excludedPrimaryTypes
Aramadan hariç tutmak için A Tablosu'ndaki 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 olmayabilir.
languageCode
belirtilmezse API varsayılan olaraken
olur. Geçersiz bir dil kodu belirtirseniz APIINVALID_ARGUMENT
hatası döndürür.- API, hem kullanıcı hem de yerel kullanıcılar tarafından okunabilen bir açık adres sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için yerel dildeki açık adresleri, gerektiğinde kullanıcı tarafından okunabilecek bir alfabeye çevrilmiş olarak, tercih edilen dili gözeterek döndürü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.
- 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ç grubu ve bunların 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ürleri için kısaltmalar veya bir dilde geçerli olup bir başka 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üdü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 konumdan uzaklığına göre artan düzende sıralar.
-
regionCode
Yanıtı biçimlendirmek için kullanılan, iki karakterli CLDR kodu değeri olarak belirtilen bölge kodu. Varsayılan değer yoktur.
Yanıttaki
formattedAddress
alanının ülke adıregionCode
ile eşleşirse ülke koduformattedAddress
öğesinden çıkarılır. Bu parametrenin, ülke adını her zaman 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 ise "gb"'dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallık'ı" için kullanılır). Parametre, geçerli yasalara göre sonuçları etkileyebilir.
Yakındaki Arama (Yeni) örnekleri
Belirli bir türdeki yerleri bulma
Aşağıdaki örnekte, 500 metrelik bir yarıçap içinde bulunan ve circle
ile tanımlanan tüm restoranların görünen adları için 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
.
Ardından yanıt şu biçimdedir:
{ "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 eklemek için places.formattedAddress,places.types,places.websiteUri
ifadesini 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çimdedir:
{ "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 yerleri bulma
Aşağıdaki örnekte, belirtilen circle
çevresinde 1.000 metre yarıçapındaki tüm market ve içki mağazalarının görünen adları için Yakındaki 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
eklenmiştir. Böylece yanıt, her bir yerle ilgili tür bilgilerini içerecek ve sonuçlar arasından uygun yeri seçmeyi kolaylaştıracaktır.
Bir yer türünü aramadan hariç tutma
Aşağıdaki örnekte "school"
türündeki tüm yerler için "primary_school"
türündeki tüm yerler hariç, sonuçları mesafeye göre sıralayan bir Yakındaki Arama (Yeni) isteği gösterilmektedir:
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
Mesafeye göre sıralamada, bir bölgenin yakınındaki tüm yerleri arama
Aşağıdaki örnekte, San Francisco şehir merkezinde bir noktanın yakınındaki yerler için bir Yakındaki Arama (Yeni) isteği gösterilmektedir. Bu örnekte, sonuçları mesafeye göre sıralamak için rankPreference
parametresini ekliyorsunuz:
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 Explorer, API'yi ve API seçeneklerini tanımanız 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'i genişletin ve
fields
parametresini alan maskesine ayarlayın. - İsteğe bağlı olarak İstek gövdesi'ni düzenleyin.
- Yürüt düğmesini seçin. Pop-up pencerede, istekte bulunurken kullanmak istediğiniz hesabı seçin.
API Gezgini panelinde API Gezgini penceresini genişletmek için genişletme simgesini () seçin.