Otomatik Tamamlama (Yeni) hizmeti, HTTP isteklerine yanıt olarak yer ve sorgu tahminleri döndüren bir web hizmetidir. İstekte bir metin arama dizesi ve arama alanını kontrol eden coğrafi sınırlar belirtin.
Otomatik Tamamlama (Yeni) hizmeti; yer adlarını, adresleri ve artı kodlarını çözümleyerek girişin tam kelimeleri ve alt dizeleriyle eşleşebilir. Bu nedenle uygulamalar, kullanıcı yazarken konum ve sorgu tahminleri sağlamak için sorguları gönderebilir.
Otomatik Tamamlama (Yeni) API'sinden gelen yanıt, iki tür tahmin içerebilir:
- Yer tahminleri: Belirtilen giriş metni dizesine ve arama alanına göre işletmeler, adresler ve önemli yerler gibi yerler. Yer tahminleri varsayılan olarak döndürülür.
- Sorgu tahminleri: Giriş metni dizesi ve arama alanıyla eşleşen sorgu dizeleri. Sorgu tahminleri varsayılan olarak döndürülmez. Yanıta sorgu tahminleri eklemek için
includeQueryPredictions
istek parametresini kullanın.
Örneğin, giriş olarak arama alanı San Francisco, CA ile sınırlı olan "Sicilya piz" şeklinde kısmi bir kullanıcı girişi içeren bir dize kullanarak API'yi çağırırsınız. Yanıtta, arama dizesiyle ve arama alanıyla (ör. "Sicilian Pizza Kitchen" adlı restoran) eşleşen yer tahminlerinin ve yerle ilgili ayrıntıların yer aldığı bir liste bulunur.
Döndürülen yer tahminleri, istenen yeri seçmelerine yardımcı olmak amacıyla kullanıcıya sunulmak üzere tasarlanmıştır. Döndürülen yer tahminleri hakkında daha fazla bilgi almak için Yer Ayrıntıları (Yeni) isteğinde bulunabilirsiniz.
Yanıt, arama dizesiyle ve arama alanıyla eşleşen "Sicilian Pizza ve Makarna" gibi sorgu tahminlerinin bir listesini de içerebilir. Yanıttaki her sorgu tahmini, önerilen bir metin arama dizesi içeren text
alanını içerir. Daha ayrıntılı bir arama yapmak için bu dizeyi Metin Arama (Yeni) işlevine girdi olarak kullanın.
API Explorer, API'yi ve API seçeneklerini tanımanız için canlı isteklerde bulunmanıza olanak tanır:
Deneyin.Otomatik tamamlama (Yeni) istekleri
Otomatik Tamamlama (Yeni) isteği, aşağıdaki formda bir URL'ye yapılan HTTP POST isteğidir:
https://places.googleapis.com/v1/places:autocomplete
Tüm parametreleri, JSON istek gövdesinde veya POST isteğinin bir parçası olarak başlıklarda iletin. Örneğin:
curl -X POST -d '{ "input": "pizza", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Yanıt hakkında
Otomatik Tamamlama (Yeni), yanıt olarak bir JSON nesnesi döndürür. Yanıtta:
suggestions
dizisi, tahmin edilen tüm yerleri ve sorguları, algılanan alaka düzeylerine göre sıralanmış olarak içerir. Her yer birplacePrediction
alanıyla temsil edilir ve her sorguqueryPrediction
alanıyla temsil edilir.placePrediction
alanı, tek bir yer tahminiyle ilgili ayrıntılı bilgiler (yer kimliği ve metin açıklaması dahil) içerir.queryPrediction
alanı, tek bir sorgu tahmini hakkında ayrıntılı bilgiler içerir.
JSON nesnesinin tamamı şu biçimdedir:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 }] }, ... }, { "queryPrediction": { "text": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 }] }, ... } ...] }
Gerekli parametreler
-
giriş
Arama yapılacak metin dizesi. Tam kelimeleri ve alt dizeleri, yer adlarını, adresleri ve artı kodlarını belirtin. Otomatik Tamamlama (Yeni) hizmeti, bu dizeye göre aday eşleşmelerini döndürür ve sonuçları algılanan alaka düzeylerine göre sıralar.
İsteğe bağlı parametreler
-
includedPrimaryTypes
Bir yerin yalnızca Tablo A veya Tablo B'de listelenen türlerden tek bir birincil türü olabilir. Örneğin, birincil tür
"mexican_restaurant"
veya"steak_house"
olabilir.Varsayılan olarak API, yerle ilişkilendirilen birincil tür değerinden bağımsız olarak
input
parametresine göre tüm yerleri döndürür.includedPrimaryTypes
parametresini ileterek sonuçları belirli bir birincil tür veya birincil türle sınırlandırın.Tablo A veya Tablo B'den en fazla beş tür değeri belirtmek için bu parametreyi kullanın. Bir yerin yanıta dahil edilmesi için belirtilen birincil tür değerlerinden biriyle eşleşmesi gerekir.
Bu parametre,
(regions)
veya(cities)
özelliklerinden birini de içerebilir. Mahalle ve posta kodları gibi bölgeler veya bölümler için(regions)
türü koleksiyon filtreleri. Google'ın şehir olarak tanımladığı yerler için(cities)
türü koleksiyonu filtreleri.İstek aşağıdaki durumlarda
INVALID_REQUEST
hatasıyla reddedilir:- Beşten fazla tür belirtildi.
(cities)
veya(regions)
dışında tüm türler belirtilir.- Tanınmayan türler belirtilmiş.
-
includeQueryPredictions
true
ise yanıt hem yer hem de sorgu tahminlerini içerir. Varsayılan değerfalse
değeridir. Yani yanıt yalnızca yer tahminlerini içerir. -
includedRegionCodes
Yalnızca belirtilen bölgeler listesinden sonuçları dahil edin. Liste, en fazla 15 adet ccTLD ("üst düzey alan") değerinde iki karakterli bir dizi şeklinde belirtilir. Atlanırsa yanıta hiçbir kısıtlama uygulanmaz. Örneğin, bölgeleri Almanya ve Fransa ile sınırlamak için:
"includedRegionCodes": ["de", "fr"]
Hem
locationRestriction
hem deincludedRegionCodes
belirtirseniz sonuçlar iki ayarın kesiştiği alanda bulunur. -
inputOffset
input
içindeki imleç konumunu gösteren sıfır tabanlı Unicode karakter ofseti. İmleç konumu, hangi tahminlerin döndürüleceğini etkileyebilir. Boş bırakılırsa varsayılan olarakinput
uzunluğu kullanılır. -
languageCode
Sonuçların döndürülmesi için tercih edilen dil.
input
dilinde kullanılan dil,languageCode
tarafından belirtilen değerden farklıysa veya döndürülen yerin yerel dildenlanguageCode
diline çevirisi yoksa sonuçlar karma dillerde olabilir.- Tercih edilen dili belirtmek için IETF BCP-47 dil kodlarını kullanmanız gerekir.
-
languageCode
sağlanmazsa APIAccept-Language
başlığında belirtilen değeri kullanır. İkisi de belirtilmemişse varsayılan değeren
olur. Geçersiz bir dil kodu belirtirseniz APIINVALID_ARGUMENT
hatası döndürü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. Bu, API'nin yazım hatalarını düzeltme özelliğini de etkiler.
-
API, hem kullanıcı hem de yerel nüfus için okunabilen bir açık adres sağlamaya çalışırken aynı zamanda kullanıcı girişini yansıtır. Yer tahminleri, her istekteki kullanıcı girişine bağlı olarak farklı şekilde biçimlendirilir.
-
İlk olarak
input
parametresindeki eşleşen terimler seçilirken, varsalanguageCode
parametresi tarafından belirtilen dil tercihiyle uyumlu adlar kullanılırken kullanıcı girişiyle en iyi eşleşen adlar kullanılır. -
Açık adresler, yalnızca
input
parametresindeki terimlerle eşleşecek şekilde eşleşen terimler seçildikten sonra, mümkün olduğunda kullanıcı tarafından okunabilecek bir komut dosyasıyla yerel dilde biçimlendirilir. -
Diğer tüm adresler,
input
parametresindeki terimlerle eşleşecek şekilde seçildikten sonra, tercih edilen dilde döndürülür. Bir ad, tercih edilen dilde sunulmuyorsa API en yakın eşleşmeyi kullanır.
-
İlk olarak
locationBias veya locationRestriction
Arama alanını tanımlamak için
locationBias
veyalocationRestriction
belirtebilirsiniz ancak ikisini birden değil.locationRestriction
özelliğini sonuçların içinde olması gereken bölgeyi,locationBias
de sonuçların yakınında olması gereken ancak alanın dışında da olabileceği bölgeyi belirtmek olarak düşünün.locationBias
Aranacak alanı belirtir. Bu konum bir ön yargı görevi görür. Yani belirtilen alanın dışındaki sonuçlar da dahil olmak üzere, belirtilen konumun çevresindeki sonuçların döndürülebileceği anlamına gelir.
locationRestriction
Aranacak alanı belirtir. Belirtilen alanın dışındaki sonuçlar döndürülmez.
locationBias
veyalocationRestriction
bölgesini dikdörtgen Görünüm veya daire olarak belirtin.Bir daire, merkez noktası ve yarıçapıyla metre cinsinden tanımlanır. Yarıçap 0,0 ile 50000,0 (her iki değer dahil) arasında olmalıdır. Varsayılan değer 0,0'dır.
locationRestriction
için yarıçapı 0,0'dan büyük bir değere ayarlamalısınız. Aksi takdirde, istek hiçbir sonuç döndürmez.Örneğin:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Dikdörtgen,
low
ile yüksek noktanın karşısında iki çapraz olarak gösterilen enlem-boylam görüntü alanıdır. Görüntü alanı, kapalı bir bölge olarak kabul edilir, yani sınırlarını içerir. Enlem sınırları -90 ile 90 derece dahil, boylam sınırları ise -180 ile 180 derece (bu değerler dahil) arasında olmalıdır:low
=high
ise görüntü alanı o tek noktadan oluşur.low.longitude
>high.longitude
ise boylam aralığı ters çevrilir (görüntü alanı 180 derecelik boylam çizgisini geçer).low.longitude
= -180 derece vehigh.longitude
= 180 derece olursa görüntü alanı tüm boylamları içerir.low.longitude
= 180 derece vehigh.longitude
= -180 dereceyse boylam aralığı boş olur.
Hem
low
hem dehigh
doldurulmalıdır. Temsil edilen kutu boş olamaz. Boş görüntü alanı hataya neden olur.Örneğin, bu görünüm New York City'yi tamamen kapsar:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
-
kaynak
Hedefe kadar olan düz çizgi mesafesinin hesaplanacağı başlangıç noktası (
distanceMeters
olarak döndürülür). Bu değer atlanırsa düz çizgi mesafesi döndürülmez. Enlem ve boylam koordinatları olarak belirtilmelidir:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
Yanıtı biçimlendirmek için kullanılan, iki karakterli ccTLD ("üst düzey alan") değeri olarak belirtilen bölge kodu. Çoğu ccTLD 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).
Geçersiz bir bölge kodu belirtirseniz API
INVALID_ARGUMENT
hatası döndürür. Parametre, geçerli yasalara göre sonuçları etkileyebilir. -
sessionToken
Oturum jetonları, Otomatik Tamamlama (Yeni) çağrılarını "oturumlar" olarak izleyen, kullanıcı tarafından oluşturulmuş dizelerdir. Otomatik Tamamlama (Yeni), bir kullanıcı otomatik tamamlama aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırmak için oturum jetonlarını kullanır. Daha fazla bilgi için Oturum jetonları bölümüne bakın.
Otomatik Tamamlama (Yeni) örnekleri
locationKısıtlama ve locationBias'ı kullanma
API, arama alanını kontrol etmek için varsayılan olarak IP'ye ağırlık vermeyi kullanır. IP'ye ağırlık verme kullanıldığında API, sonuçlara ağırlık vermek için cihazın IP adresini kullanır. İsteğe bağlı olarak, aranacak bir alan belirtmek için locationRestriction
veya locationBias
kullanabilirsiniz, ancak ikisini birden kullanamazsınız.
locationRestriction
, aranacak alanı belirtir. Belirtilen alanın dışındaki sonuçlar döndürülmez. Aşağıdaki örnekte, isteği San Francisco merkezli yarıçapı 5.000 metrelik bir daireyle sınırlamak için locationRestriction
öğesini kullanırsınız:
curl -X POST -d '{ "input": "Amoeba", "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Belirtilen alanlardan gelen tüm sonuçlar suggestions
dizisinde bulunur:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "store", "point_of_interest", "electronics_store" ] } } ] }
locationBias
kullanıldığında konum bir ağırlık görevi görür. Bu da belirtilen alanın dışındaki sonuçlar da dahil olmak üzere, belirtilen konum etrafındaki sonuçların döndürülebileceği anlamına gelir. Bir sonraki örnekte, isteği locationBias
kullanılacak şekilde değiştiriyorsunuz:
curl -X POST -d '{ "input": "Amoeba", "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Sonuçlar artık, 5000 metre yarıçapın dışındaki sonuçlar da dahil olmak üzere çok daha fazla öğe içermektedir:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
dahiledPrimaryTypes kullanın
Tablo A, Tablo B veya yalnızca (regions)
ya da yalnızca (cities)
öğesinden en fazla beş tür değeri belirtmek için includedPrimaryTypes
parametresini kullanın. Bir yerin yanıta dahil edilmesi için belirtilen birincil tür değerlerden biriyle eşleşmesi gerekir.
Aşağıdaki örnekte, "Futbol" türünde bir input
dizesi belirtiyor ve sonuçları "sporting_goods_store"
türündeki kuruluşlarla kısıtlamak için includedPrimaryTypes
parametresini kullanıyorsunuz:
curl -X POST -d '{ "input": "Soccer", "includedPrimaryTypes": ["sporting_goods_store"], "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
includedPrimaryTypes
parametresini çıkarırsanız sonuçlar, "athletic_field"
gibi istemediğiniz bir türdeki yerleşimleri içerebilir.
İstek sorgusu tahminleri
Sorgu tahminleri varsayılan olarak döndürülmez. Yanıta sorgu tahminleri eklemek için includeQueryPredictions
istek parametresini kullanın. Örneğin:
curl -X POST -d '{ "input": "Amoeba", "includeQueryPredictions": true, "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
suggestions
dizisi artık, yukarıdaki Yanıt hakkında bölümünde gösterildiği gibi hem yer tahminlerini hem de sorgu tahminlerini içeriyor. Her sorgu tahmini, önerilen bir metin arama dizesi içeren text
alanını içerir. Döndürülen sorgu tahminlerinin herhangi biri hakkında daha fazla bilgi almak için Metin Arama (Yeni) isteğinde bulunabilirsiniz.
Başlangıç noktasını kullan
Bu örnekte, isteğe enlem ve boylam koordinatları olarak origin
öğesini ekleyin.
origin
özelliğini eklediğinizde API, origin
ile hedefe olan düz çizgi mesafesini içeren distanceMeters
alanını yanıta ekler.
Bu örnek, başlangıç noktasını San Francisco'nun merkezine ayarlar:
curl -X POST -d '{ "input": "Amoeba", "origin": { "latitude": 37.7749, "longitude": -122.4194 }, "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Yanıtta artık distanceMeters
var:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
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.