Otomatik Tamamla (Yeni)

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 bir placePrediction alanıyla temsil edilir ve her sorgu queryPrediction 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ğer false 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 de includedRegionCodes 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 olarak input 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 dilden languageCode 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 API Accept-Language başlığında belirtilen değeri kullanır. İkisi de belirtilmemişse varsayılan değer en olur. 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ç 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, varsa languageCode 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.
  • locationBias veya locationRestriction

    Arama alanını tanımlamak için locationBias veya locationRestriction 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 veya locationRestriction 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 ayarlamanız gerekir. Diğer durumlarda istek 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 ve high.longitude = 180 derece olursa görüntü alanı tüm boylamları içerir.
      • low.longitude = 180 derece ve high.longitude = -180 dereceyse boylam aralığı boş olur.

      Hem low hem de high 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
      }
    }
  ]
}