Otomatik Tamamlama (Yeni) hizmeti, HTTP isteğine yanıt olarak yer tahminleri 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, girişin tam kelimeleri ve alt dizeleriyle eşleşerek yer adlarını, adresleri ve artı kodlarını çözümleyebilir. Bu nedenle uygulamalar, anında yer ve sorgu tahminleri sağlamak için kullanıcı yazarken sorgular gönderebilir.
Autocomplete (Yeni) API'den gelen yanıt iki tür tahmin içerebilir:
- Yer tahminleri: Belirtilen giriş metni dizesine ve arama alanına dayalı olarak 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, kısmi kullanıcı girişini içeren "Sicilian piz" ifadesini içeren bir dize kullanarak API'yi çağırabilirsiniz. Arama alanı San Francisco, Kaliforniya ile sınırlıdır. Daha sonra yanıt, arama dizesi ve arama alanıyla eşleşen yer tahminlerinin (ör. "Sicilian Pizza Kitchen" adlı restoran) ve yerle ilgili ayrıntıların bir listesini içerir.
Döndürülen yer tahminleri, kullanıcıya istenen yeri seçmesine yardımcı olmak amacıyla sunulacak şekilde tasarlanmıştır. Döndürülen yer tahminlerinden herhangi biri hakkında daha fazla bilgi almak için Yer Ayrıntıları (Yeni) isteğinde bulunabilirsiniz.
Yanıt, arama dizesi ve arama alanıyla eşleşen sorgu tahminlerinin (ör. "Sicilian Pizza & Pasta") bir listesini de içerebilir. Yanıttaki her sorgu tahmini, önerilen metin arama dizesi içeren text
alanını içerir. Bu dizeyi, daha ayrıntılı bir arama yapmak için Metin Arama (Yeni) işlevinde giriş olarak kullanın.
API Gezgini, API ve API seçenekleri hakkında bilgi sahibi olmak için canlı istekler yapmanıza olanak tanır:
Deneyin.Otomatik tamamlama (Yeni) istekleri
Otomatik Tamamlama (Yeni) isteği, aşağıdaki biçimde bir URL'ye yapılan HTTP POST isteğidir:
https://places.googleapis.com/v1/places:autocomplete
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 '{ "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ırayla içerir. Her yerplacePrediction
alanıyla ve her sorguqueryPrediction
alanıyla temsil edilir.placePrediction
alanında yer kimliği ve metin açıklaması da dahil olmak üzere tek bir yer tahmini hakkında ayrıntılı bilgiler yer alır.queryPrediction
alanı, tek bir sorgu tahmini hakkında ayrıntılı bilgiler içerir.
JSON nesnesinin tamamı aşağıdaki 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 dayalı aday eşleşmeleri döndürür ve sonuçları algılanan alaka düzeyine göre sıralar.
İsteğe bağlı parametreler
-
includedPrimaryTypes
Bir yerin, A Tablosu veya B Tablosu'nda listelenen türlerden yalnızca tek bir birincil türü olabilir. Örneğin, birincil tür
"mexican_restaurant"
veya"steak_house"
olabilir.Varsayılan olarak API, yerle ilişkilendirilmiş 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ürde veya birincil türde olacak şekilde 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, bunun yerine
(regions)
veya(cities)
özelliklerinden birini de içerebilir. Mahalleler ve posta kodları gibi alanlar veya bölümler için(regions)
türü toplama filtreleri. Google'ın şehir olarak tanımladığı yerler için(cities)
türündeki toplama filtreleri.Aşağıdaki durumlarda istek
INVALID_REQUEST
hatasıyla reddedilir:- Beşten fazla tür belirtilmiş.
(cities)
veya(regions)
öğesine ek olarak 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
, yani yanıt yalnızca yer tahminlerini içerir. -
includedRegionCodes
Yalnızca, en fazla 15 ccTLD ("üst düzey alan") iki karakterlik değerden oluşan bir dizi olarak belirtilen, belirtilen bölgeler listesinden sonuçları dahil edin. Atlanırsa yanıta herhangi 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
öğesini belirtirseniz sonuçlar iki ayarın kesişim alanında yer alır. -
inputOffset
input
içindeki imleç konumunu gösteren sıfır tabanlı Unicode karakter farkı. İmleç konumu, hangi tahminlerin döndürüleceğini etkileyebilir. Boşsa varsayılan olarakinput
uzunluğunda olur. -
languageCode
Sonuçların döndürüleceği tercih edilen dil.
input
içinde kullanılan dil,languageCode
tarafından belirtilen değerden farklıysa veya döndürülen yerde yerel dildenlanguageCode
diline çeviri yoksa sonuçlar karışık dilde olabilir.- Tercih edilen dili belirtmek için IETF BCP-47 dil kodlarını kullanmanız gerekir.
-
languageCode
sağlanmazsa API,Accept-Language
başlığında belirtilen değeri kullanır. İkisi de belirtilmezse varsayılan olaraken
kullanılır. Geçersiz bir dil kodu belirtirseniz API,INVALID_ARGUMENT
hatası döndürü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. Bu durum, API'nin yazım hatalarını düzeltme becerisini de etkiler.
-
API, aynı zamanda kullanıcı girişini yansıtırken hem kullanıcı hem de yerel nüfus için okunabilen bir açık adres sağlamaya çalışır. Yer tahminleri, her istekteki kullanıcı girişine bağlı olarak farklı şekilde biçimlendirilir.
-
İlk olarak
input
parametresindeki eşleşen terimler, mümkün olduğundalanguageCode
parametresi tarafından belirtilen dil tercihiyle uyumlu adlar, diğer durumlarda ise kullanıcı girişiyle en iyi eşleşen adlar kullanılarak seçilir. -
Açık adresler yalnızca
input
parametresindeki terimlerle eşleşecek terimler seçildikten sonra yerel dilde, mümkün olduğunda kullanıcı tarafından okunabilecek bir alfabede biçimlendirilir. -
Diğer tüm adresler,
input
parametresindeki terimlerle eşleşecek şekilde eşleşen terimler 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
Konum ön yargıları veya konum Kısıtlaması
Arama alanını tanımlamak için
locationBias
veyalocationRestriction
belirtebilirsiniz ancak ikisini birden belirtemezsiniz.locationRestriction
öğesini, sonuçların içinde olması gereken bölgeyi belirtmek,locationBias
öğesini de sonuçların yakınında olması gereken ancak bölgenin dışında olabilecek bölgeyi belirtmek olarak düşünebilirsiniz.locationBias
Aranacak alanı belirtir. Bu konum bir sapma görevi görür. Bu da belirtilen alanın dışındaki sonuçlar da dahil olmak üzere belirtilen konumun etrafındaki 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
ya dalocationRestriction
bölgesini dikdörtgen Viewport veya daire olarak belirtin.Bir daire, merkez noktası ve metre cinsinden yarıçapla tanımlanır. Yarıçap, 0,0 ile 50.000,0 (her ikisi de 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 ayarlamanız gerekir. 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
yönünde çapraz olarak iki ve yüksek noktayla temsil edilen enlem-boylam görüntü alanıdır. Görüntü alanı, kapalı bölge olarak kabul edilir. Yani kendi sınırlarını içerir. Enlem sınırları -90 ile 90 derece (dahil) arasında, boylam sınırları ise -180 ila 180 derece (her ikisi de dahil) arasında olmalıdır:low
=high
olursa, görüntü alanı bu tek noktadan oluşur.low.longitude
>high.longitude
ise boylam aralığı tersine çevrilir (görüntü alanı 180 derecelik boylam çizgisini geçer).low.longitude
= -180 derece vehigh.longitude
= 180 derece ise görüntü alanı tüm boylamları içerir.low.longitude
= 180 derece vehigh.longitude
= -180 derece ise boylam aralığı boş olur.
Hem
low
hem dehigh
doldurulmalı ve gösterilen kutu boş bırakılamaz. Boş görüntü alanı hatayla sonuçlanır.Örneğin, bu görüntü alanı New York City'yi tamamen kapsar:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
-
kaynak
Hedefe 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 bölge kodu. İki karakterlik bir ccTLD ("üst düzey alan") değeri olarak belirtilir. ccTLD 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), 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.
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), 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ı kullanır. Daha fazla bilgi için Oturum jetonları bölümünü inceleyin.
Otomatik tamamlama (Yeni) örnekleri
Konum kısıtlaması ve konum önerileri kullan
API, arama alanını kontrol etmek için varsayılan olarak IP ağırlıklandırmayı kullanır. IP'ye ağırlık vermede API, sonuçlara ağırlık vermek için cihazın IP adresini kullanır. İsteğe bağlı olarak locationRestriction
veya locationBias
kullanabilirsiniz ancak aranacak bir alan belirtmek için 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 5.000 metre yarıçapındaki bir daireyle sınırlamak için locationRestriction
kullanılmıştır:
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 yer alır:
{ "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
ile konum bir sapma görevi görür. Bu da belirtilen alanın dışındaki sonuçlar da dahil olmak üzere belirtilen konumun etrafındaki sonuçların döndürülebileceği anlamına gelir. Bir sonraki örnekte, isteği locationBias
kullanacak ş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çeriyor:
{ "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" ] } }, ... ] }
includePrimaryTypes örneğinde olduğu gibi,
Tablo A, Tablo B veya yalnızca (regions)
ya da yalnızca (cities)
türünde 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ğerlerinden biriyle eşleşmesi gerekir.
Aşağıdaki örnekte "Futbol" input
dizesini belirtir ve sonuçları "sporting_goods_store"
türündeki kuruluşlarla kısıtlamak için includedPrimaryTypes
parametresini kullanırsınız:
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 kuruluşları içerebilir.
Sorgu tahminleri isteme
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çerir. Her sorgu tahmini, önerilen metin arama dizesini içeren text
alanını içerir. Döndürülen sorgu tahminlerinden herhangi biri hakkında daha fazla bilgi almak için Metin Arama (Yeni) isteğinde bulunabilirsiniz.
Kaynağı kullan
Bu örnekte, enlem ve boylam koordinatları olarak isteğe origin
ekleyin.
origin
öğesini eklediğinizde API, yanıta origin
ile hedefe arasındaki düz çizgiyi içeren distanceMeters
alanını dahil eder.
Bu örnekte başlangıç noktası San Francisco'nun merkezi olarak ayarlanmaktadır:
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ıt artık distanceMeters
içeriyor:
{ "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 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.