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.
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
Otomatik tamamlamayı kullanarak istekte bulunma (Yeni)
Places API, mevcut Autocomplete ve Query Autocomplete API'lerini destekler. Bu API'ler hakkında bilginiz varsa Otomatik Tamamlama'nın Önizleme sürümü (Yeni) aşağıdaki değişiklikleri yapar:- Yeni Otomatik Tamamlama, HTTP POST isteklerini kullanır. Parametreleri istek gövdesine veya bir HTTP POST isteğinin parçası olarak başlıklara iletin. Buna karşılık, mevcut API'lerde URL parametrelerini bir HTTP GET isteği kullanarak geçirirsiniz.
- Yeni Otomatik Tamamlama, kimlik doğrulama mekanizması olarak hem API anahtarlarını hem de OAuth jetonlarını destekler.
- Yeni Otomatik Tamamlama'da yanıt biçimi olarak yalnızca JSON desteklenir.
Aşağıdaki tabloda, mevcut Otomatik Tamamlama ve Sorgu Otomatik Tamamlama API'lerinde bulunan, yeni Otomatik Tamamlama için yeniden adlandırılmış veya değiştirilmiş parametreler ya da artık desteklenmeyen parametreler listelenmektedir.
Geçerli parametre | Yeni parametre | Notlar |
---|---|---|
components |
includedRegionCodes |
|
language |
languageCode |
|
location |
locationBias |
|
ipbias |
Hem locationBias hem de locationRestriction öğesini çıkarırsanız API varsayılan olarak IP'ye ağırlık vermeyi kullanır. |
|
offset |
inputOffset |
|
radius |
locationBias veya locationRestriction |
|
region |
regionCode |
|
stricbounds |
locationRestriction |
|
sessiontoken |
sessionToken |
|
types |
includedPrimaryTypes |
Kullanım sınırları
Önizleme sürümünde, proje başına dakikada maksimum 600 sorgu yapabilirsiniz.
Önizleme sürümleri için destek seçenekleri
Google'ın Hizmetler'in Önizleme sürümleri, özellikleri veya işlevleri için destek sağlama yükümlülüğü olmasa da bu geliştirme aşamalarındaki istekleri tek tek ele alırız.
- Yayın öncesi sürümler Google Haritalar Platformu HDS'si kapsamında değildir.
- Özellikle üretim ortamında yayın öncesi sürüm kullanıyorsanız yedek mekanizmaların kullanılması önerilir. Yedek durumlarına örnek olarak kota aşıldı, beklenmedik yanıt kodları ve gecikme veya mevcut Otomatik tamamlama ile karşılaştırıldığında beklenmedik yanıtlar verilebilir.
Yeni özellikler istemek veya mevcut özelliklerde değişiklik önermek için sorun izleyiciyi kullanabilirsiniz. Lütfen eklenmesini istediğiniz belirli bir işlevi ve bunun önemli olduğunu düşünmenizin nedenlerini açıklayın. Mümkünse kullanım alanınız ve özelliğin sağlayacağı yeni fırsatlar hakkında belirli ayrıntıları ekleyin:
Özelliklerle ilgili diğer tüm sorularınız için lütfen newplacesapi@google.com adresine e-posta gönderin.
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 kendisiyle ilişkili Tablo A veya Tablo B türlerinden 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.
İstek aşağıdaki durumlarda
INVALID_REQUEST
hatasıyla reddedilir:- Beşten fazla tür belirtildi.
- 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 listesindeki 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
ise sonuçların yakınında olması gereken ancak alanın dışında olabilecek 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
Bir isteğin sonuçlarını Tablo A ve Tablo B'de listelendiği gibi belirli bir türden olacak şekilde kısıtlamak için includedPrimaryTypes
parametresini kullanın. En fazla beş değerden oluşan bir dizi belirtebilirsiniz.
Atlanırsa tüm türler döndürülür.
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 } } ] }