Otomatik Tamamla (Yeni)

Platform seçin: Android iOS JavaScript Web Hizmeti

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 yer placePrediction alanıyla ve her sorgu queryPrediction 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ğer false, 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 de includedRegionCodes öğ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 olarak input 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 dilden languageCode 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 olarak en 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ğunda languageCode 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.

  • Konum ön yargıları veya konum Kısıtlaması

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

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

  1. Sayfanın sağ tarafındaki API simgesini (API Gezgini'ni genişletin.) seçin.
  2. İsteğe bağlı olarak Standart parametreleri göster seçeneğini genişletin ve fields parametresini alan maskesi olarak ayarlayın.
  3. İsteğe bağlı olarak İstek gövdesini düzenleyin.
  4. Yürüt düğmesini seçin. Pop-up pencerede, istekte bulunmak için kullanmak istediğiniz hesabı seçin.

  5. API Gezgini panelinde genişletme simgesini (API Gezgini'ni genişletin.) seçerek API Gezgini penceresini genişletin.