Otomatik Tamamla (Yeni)

Giriş

Autocomplete (New), bir HTTP isteğine yanıt olarak yer tahminleri ve sorgu tahminleri döndüren bir web hizmetidir. İstekte, arama alanını kontrol eden bir metin arama dizesi ve coğrafi sınırlar belirtin.

Otomatik Tamamlama (Yeni), tam kelimeler ve girişin alt dizeleriyle eşleşebilir, yer adlarını, adresleri ve Plus Code'ları çözebilir. Bu nedenle uygulamalar, kullanıcı yazarken sorgu göndererek anında yer ve sorgu tahminleri sağlayabilir.

Otomatik Tamamlama (Yeni) özelliğinin yanıtı iki tür tahmin içerebilir:

• Yer tahminleri: Belirtilen giriş metni dizesine ve arama alanına göre işletmeler, adresler ve ilgi çekici 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, arama alanı Kaliforniya, San Francisco ile sınırlı olan ve kısmi kullanıcı girişi "Sicilian piz" içeren bir dizeyi giriş olarak kullanarak otomatik tamamlama (yeni) işlevini çağırıyorsunuz. Yanıt, arama dizesi ve arama alanıyla eşleşen yer tahminlerinin listesini (ör. "Sicilian Pizza Kitchen" adlı restoran) ve yerle ilgili ayrıntıları içerir.

Döndürülen yer tahminleri, kullanıcılara sunulmak ve amaçlanan yeri seçmelerine yardımcı olmak için tasarlanmıştır. Döndürülen yer tahminlerinden herhangi biri hakkında daha fazla bilgi edinmek için Yer Ayrıntıları (Yeni) isteğinde bulunabilirsiniz.

Yanıtta, arama dizesi ve arama alanıyla eşleşen sorgu tahminlerinin listesi de (ör. "Sicilian Pizza & Pasta") yer alabilir. Yanıtın her sorgu tahmininde, önerilen bir metin arama dizesini içeren text alanı bulunur. Daha ayrıntılı bir arama yapmak için bu dizeyi Text Search (New) için giriş olarak kullanın.

API Gezgini, API ve API seçeneklerini tanıyabilmeniz için canlı istekler göndermenize olanak tanır:

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 istek 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

Desteklenen parametreler

Yanıt hakkında

Otomatik Tamamlama (Yeni), yanıt olarak bir JSON nesnesi döndürür. Yanıtın içinde:

• suggestions dizisi, algılanan alaka düzeylerine göre sıralanmış tüm tahmin edilen yerleri ve sorguları içerir. Her yer bir placePrediction alanı, her sorgu ise bir queryPrediction alanı ile gösterilir.
• placePrediction alanı, yer kimliği ve metin açıklaması dahil olmak üzere tek bir yer tahminiyle ilgili ayrıntılı bilgiler içerir.
  • input parametresinde sağlanan kullanıcı girişiyle daha yakından eşleşmesi için bir yer tahmininin metin açıklaması; yerler, sokaklar ve diğer adres bileşenleri için alternatif adlar içerebilir. Bu alternatif adlar, aynı yer kimliği için yer ayrıntıları sonuçlarının displayName ve adres alanlarında döndürülen adlardan farklı olabilir.
  • Bu bağlamda, bazı yerlerin alternatif adları, kullanıcı girişine daha yakın olan adlara bağlı olarak languageCode parametresine göre beklenenden farklı bir dilde olabilir.
• queryPrediction alanı, tek bir sorgu tahminiyle ilgili ayrıntılı bilgileri içerir.

Tam JSON nesnesi ş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 Plus kodlarını belirtin. Otomatik Tamamlama (Yeni) hizmeti, bu dizeye göre olası eşleşmeleri döndürür ve sonuçları algılanan alaka düzeylerine göre sıralar.

İsteğe bağlı parametreler

• FieldMask

  Bir yanıt alanı maskesi oluşturarak yanıtta döndürülecek alanların listesini belirtin. HTTP üst bilgisi X-Goog-FieldMask'yı kullanarak yanıt alan maskesini yönteme iletin.

  Döndürülecek öneri alanlarının virgülle ayrılmış listesini belirtin. Örneğin, önerinin suggestions.placePrediction.text.text ve suggestions.queryPrediction.text.text değerlerini almak için.

    X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

  Tüm alanları almak için * kullanın.

    X-Goog-FieldMask: *

• includeFutureOpeningBusinesses

  true, gelecekte açılması beklenen işletmeleri döndürür. Varsayılan değer false'dir.

• includedPrimaryTypes

  Bir yer, Tablo A veya Tablo B'de listelenen türlerden yalnızca tek bir birincil türe sahip olabilir. Örneğin, birincil tür "mexican_restaurant" veya "steak_house" olabilir.

  API, varsayılan olarak yerle ilişkili 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ürlerle 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) değerlerinden birini de içerebilir. (regions) türü koleksiyon, mahalleler ve posta kodları gibi alanlar veya bölümler için filtreleme yapar. (cities) türü koleksiyon, Google'ın şehir olarak tanımladığı yerleri filtreler.

  İstek şu durumlarda INVALID_REQUEST hatasıyla reddedilir:

  • Beşten fazla tür belirtilmiş.
  • (cities) veya (regions) dışında bir tür belirtildi.
  • Tanınmayan türler belirtilir.

• includePureServiceAreaBusinesses

  true olarak ayarlanırsa yanıt, müşterileri doğrudan ziyaret eden veya onlara teslimat yapan ancak fiziksel bir işletme konumu olmayan işletmeleri içerir. false olarak ayarlanırsa API yalnızca fiziksel bir işletme konumuna sahip işletmeleri döndürür.

• includeQueryPredictions

  true ise yanıt hem yer hem de sorgu tahminlerini içerir. Varsayılan değer false olup yanıtın yalnızca yer tahminlerini içerdiği anlamına gelir.

• includedRegionCodes

  Yalnızca belirtilen bölgeler listesindeki sonuçları dahil edin. Bu liste, en fazla 15 ccTLD ("ülke kodu üst düzey alan adı") iki karakterli değerden oluşan bir dizi olarak belirtilir. Atlanırsa yanıta 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şim alanında yer alır.

• inputOffset

  input içinde 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ğunda olur.

• languageCode

  Sonuçların döndürülmesinde tercih edilen dil. input içinde 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 karışık 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 belirtilmezse varsayılan değer en olur. Geçersiz bir dil kodu belirtirseniz API, INVALID_ARGUMENT hatası döndürür.
  • Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç kümesi ve bu sonuçların döndürülme sırası üzerinde küçük bir etkiye sahiptir. Bu durum, API'nin yazım hatalarını düzeltme özelliğini de etkiler.
  • Yer tahminleri, her istekteki kullanıcı girişine bağlı olarak farklı şekilde biçimlendirilir.
    • input parametresindeki eşleşen terimler, varsa languageCode parametresiyle belirtilen dil tercihine uygun adlar kullanılarak, aksi takdirde kullanıcı girişine en iyi şekilde uyan adlar kullanılarak önce seçilir.
    • Yer adları, input parametresindeki terimlerle eşleşmesi için alternatif adlar kullanılarak biçimlendirilebilir. Bu adlar, languageCode parametresiyle belirtilen dilin dışındaki dillerdeki adları da içerir.
    • Sokak adresleri, mümkün olduğunda yerel dilde ve kullanıcı tarafından okunabilir bir alfabeyle biçimlendirilir. Bu işlem, yalnızca input parametresindeki terimlerle eşleşecek terimler seçildikten sonra yapılır.
    • Diğer tüm adresler, input parametresindeki terimlerle eşleşecek terimler seçildikten sonra tercih edilen dilde döndürülür. Tercih edilen dilde ad yoksa API en yakın eşleşmeyi kullanır.

• locationBias veya locationRestriction

  Arama alanını tanımlamak için locationBias veya locationRestriction değerini belirtebilirsiniz ancak ikisini birden belirtemezsiniz. locationRestriction, sonuçların içinde olması gereken bölgeyi belirtir. locationBias ise sonuçların yakınında olması gereken ancak alanın dışında olabileceği bölgeyi belirtir.

  • locationBias

    Arama yapılacak bir alanı belirtir. Bu konum, bir önyargı olarak işlev görür. Bu nedenle, belirtilen alanın dışındaki sonuçlar da dahil olmak üzere belirtilen konumla ilgili sonuçlar döndürülebilir.

  • locationRestriction

    Arama yapılacak alanı belirtir. Belirtilen alanın dışındaki sonuçlar döndürülmez.

  locationBias veya locationRestriction bölgesini dikdörtgen bir görünüm alanı ya da daire olarak belirtin.

  • Bir daire, merkez noktası ve metre cinsinden yarıçap ile tanımlanır. Yarıçap, 0,0 ile 50.000,0 arasında (bu değerler dahil) 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, sonuç döndürmez.

    Örneğin:

    "locationBias": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

  • Dikdörtgen, iki çapraz zıt low ve yüksek nokta olarak gösterilen bir enlem-boylam görünüm alanıdır. Görüntü alanı kapalı bir bölge olarak kabul edilir. Bu nedenle, sınırları da görüntü alanına dahildir. Enlem sınırları -90 ile 90 derece arasında, boylam sınırları ise -180 ile 180 derece arasında olmalıdır:

    • low = high ise görüntü alanı tek bir noktadan oluşur.
    • low.longitude > high.longitude ise boylam aralığı ters çevrilir (görüntü alanı 180 derece 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ıdır ve temsil edilen kutu boş olamaz. Boş bir görünüm penceresi hataya neden olur.

    Örneğin, bu görünüm penceresi New York şehrini tamamen kapsıyor:

    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 40.477398,
          "longitude": -74.259087
        },
        "high": {
          "latitude": 40.91618,
          "longitude": -73.70018
        }
      }
    }

• kaynak

  Hedefe 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, iki karakterlik bir ccTLD ("üst düzey alan") değeri olarak belirtilir. Bazı önemli istisnalar dışında çoğu ccTLD kodu, ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk) iken ISO 3166-1 kodu "gb"dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallığı" tüzel kişiliği için).

  Öneriler, bölge kodlarına göre de önceliklendirilir. Google, regionCode değerini kullanıcının bölgesel tercihine göre ayarlamanızı önerir.

  Geçersiz bir bölge kodu belirtirseniz API, INVALID_ARGUMENT hatası döndürür. Bu parametre, geçerli yasaya bağlı olarak sonuçları etkileyebilir.

• sessionToken

  Oturum jetonları, kullanıcı tarafından oluşturulan ve otomatik tamamlama (yeni) çağrılarını "oturum" olarak izleyen dizelerdir. Otomatik tamamlama (yeni), kullanıcının otomatik tamamlama aramasıyla ilgili 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ı başlıklı makaleyi inceleyin.

Sonuçları etkileyecek parametreleri seçin

Otomatik tamamlama (yeni) örnekleri

locationRestriction kullanarak aramayı bir alanla sınırlama

locationRestriction, arama yapılacak alanı belirtir. Belirtilen alanın dışındaki sonuçlar döndürülmez. Aşağıdaki örnekte, isteği San Francisco'nun merkezinde bulunan 5.000 metre yarıçaplı bir daire ile sınırlamak için locationRestriction kullanıyorsunuz:

curl -X POST -d '{
  "input": "Art museum",
  "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 alanlardaki tüm sonuçlar suggestions dizisinde yer alır:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

Aramaları dikdörtgen bir görüntü alanıyla sınırlamak için locationRestriction parametresini de kullanabilirsiniz. Aşağıdaki örnek, isteği San Francisco şehir merkeziyle sınırlar:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Sonuçlar suggestions dizisinde yer alır:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

locationBias kullanarak aramayı bir alana yönlendirme

locationBias ile konum, bir önyargı olarak işlev görür. Bu nedenle, belirtilen konumun dışındaki sonuçlar da dahil olmak üzere belirtilen konumun çevresindeki sonuçlar döndürülebilir. Aşağıdaki örnekte, isteği İstanbul şehir merkezine yönlendiriyorsunuz:

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 5.000 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"
        ]
      }
    },
    ...
  ]
}

Aramaları dikdörtgen bir görünüm penceresine yönlendirmek için locationBias öğesini de kullanabilirsiniz. Aşağıdaki örnekte, istek San Francisco'nun şehir merkeziyle sınırlandırılmıştır:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Dikdörtgen görünüm alanındaki arama sonuçları yanıtta görünse de bazı sonuçlar, önyargı nedeniyle tanımlanan sınırların dışında kalır. Sonuçlar suggestions dizisinde de 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": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "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": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

includedPrimaryTypes'ı kullanın

includedPrimaryTypes parametresini kullanarak Tablo A, Tablo B veya yalnızca (regions) ya da yalnızca (cities)'dan en fazla beş tür değeri belirtebilirsiniz. Yanıtın dahil edilmesi için bir yer, belirtilen birincil tür değerlerinden biriyle eşleşmelidir.

Aşağıdaki örnekte, input dizesini "Futbol" olarak belirtiyor ve sonuçları "sporting_goods_store" türündeki kuruluşlarla sınırlamak 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 atlarsanız sonuçlar, "athletic_field" gibi istemediğiniz türde işletmeleri 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 hem yer tahminlerini hem de sorgu tahminlerini içerir. Bu durum, yukarıda Yanıt hakkında bölümünde gösterilmiştir. Her sorgu tahmini, önerilen bir metin arama dizesini içeren text alanını içerir. Döndürülen sorgu tahminlerinden herhangi biri hakkında daha fazla bilgi edinmek için Metin Arama (Yeni) isteğinde bulunabilirsiniz.

Kaynak kullan

Bu örnekte, isteğe enlem ve boylam koordinatları olarak origin değerini ekleyin. origin değerini eklediğinizde Otomatik Tamamlama (Yeni), yanıta origin ile hedef arasındaki düz çizgi mesafesini içeren distanceMeters alanını ekler. Bu örnekte başlangıç noktası San Francisco'nun merkezine ayarlanı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
      }
    }
  ]
}

Gelecekte açılacak işletmeleri bulma

Aşağıdaki örnekte, New Meadows, Idaho'da gelecekte açılacak işletmeler için bir otomatik tamamlama (yeni) isteği gösterilmektedir:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

Yanıt, yerle ilgili ayrıntılar içeriyor ancak açılış tarihini içermiyor.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

Yanıtta mesafe bilgisi yok

Bazı durumlarda, origin isteğe dahil edilmiş olsa bile distanceMeters yanıt gövdesinde eksik oluyor. Bu durum aşağıdaki senaryolarda yaşanabilir:

• distanceMeters, route tahminlerine dahil edilmez.
• distanceMeters, değeri 0 olduğunda dahil edilmez. Bu durum, sağlanan origin konumundan 1 metreden daha az uzaklıktaki tahminler için geçerlidir.

Ayrıştırılmış bir nesneden distanceMeters alanını okumaya çalışan istemci kitaplıkları, 0 değerine sahip bir alan döndürür. Kullanıcıları yanıltmamak için kullanıcılara sıfır mesafe göstermeyin.

Otomatik tamamlama (yeni) optimizasyonu

Bu bölümde, Otomatik Tamamlama (Yeni) hizmetinden en iyi şekilde yararlanmanıza yardımcı olacak en iyi uygulamalar açıklanmaktadır.

Genel kurallardan bazıları şunlardır:

• Çalışan bir kullanıcı arayüzü geliştirmenin en hızlı yolu şunları kullanmaktır: Maps JavaScript API Autocomplete (New) widget'ı, Android için Yerler SDK'sı Autocomplete (New) widget'ı, veya iOS için Yerler SDK'sı Autocomplete (New) widget'ı.
• Temel Autocomplete (New) veri alanlarını en baştan anlayın.
• Konum tercihi ve konum kısıtlama alanları isteğe bağlıdır ancak otomatik tamamlama performansı üzerinde önemli bir etkiye sahip olabilir.
• API bir hata döndürürse uygulamanızın düzgün bir şekilde çalışmaya devam etmesi için hata işleme özelliğini kullanın.
• Uygulamanızın, seçim yapılmadığında bu durumu ele aldığından ve kullanıcılara devam etme yolu sunduğundan emin olun.

Maliyet optimizasyonuyla ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Otomatik Tamamlama (Yeni) hizmetini kullanma maliyetini optimize etmek için Yer Ayrıntıları (Yeni) ve Otomatik Tamamlama (Yeni) widget'larında alan maskeleri kullanarak yalnızca ihtiyacınız olan Otomatik Tamamlama (Yeni) veri alanlarını döndürün.

Gelişmiş maliyet optimizasyonu

Aşağıdakilere erişmek için Otomatik Tamamlama (Yeni) özelliğini programatik olarak uygulamayı düşünebilirsiniz: SKU: Otomatik Tamamlama İsteği fiyatlandırması Ayrıca, Yer Ayrıntıları (Yeni) yerine seçilen yerle ilgili Geocoding API sonuçları isteğinde bulunabilirsiniz. Aşağıdaki koşulların her ikisi de karşılanıyorsa Geocoding API'si ile birlikte kullanılan istek başına fiyatlandırma, oturum başına (oturum tabanlı) fiyatlandırmaya kıyasla daha uygun maliyetlidir:

• Kullanıcının seçtiği yerin yalnızca enlem ve boylamı veya adresi gerekiyorsa Geocoding API, bu bilgileri Yer Ayrıntıları (Yeni) çağrısından daha düşük bir maliyetle sağlar.
• Kullanıcılar, ortalama dört veya daha az Otomatik Tamamlama (Yeni) tahmin isteği içinde bir otomatik tamamlama tahmini seçerse istek başına fiyatlandırma, oturum başına fiyatlandırmaya göre daha uygun maliyetli olabilir.

Uygulamanız, seçilen tahminin adresi ve enlem/boylamı dışında başka bilgi gerektiriyor mu?

Performansla ilgili en iyi uygulamalar

Aşağıdaki yönergelerde, Otomatik Tamamlama (Yeni) performansını optimize etmenin yolları açıklanmaktadır:

• Otomatik Tamamlama (Yeni) uygulamanıza ülkeye özgü kısıtlamalar, konum ağırlığı ve (programatik uygulamalar için) dil tercihleri ekleyin. Dil tercihi, kullanıcının tarayıcısından veya mobil cihazından dil tercihlerini alan widget'larda gerekli değildir.
• Autocomplete (New) özelliğine bir harita eşlik ediyorsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
• Kullanıcının, genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığı için Otomatik Tamamlama (Yeni) tahminlerinden birini seçmediği durumlarda, daha alakalı sonuçlar elde etmek için orijinal kullanıcı girişini yeniden kullanabilirsiniz:
  • Kullanıcının yalnızca adres bilgisi girmesini bekliyorsanız Geocoding API'ye yapılan bir çağrıda orijinal kullanıcı girişini yeniden kullanın.
  • Kullanıcının belirli bir yerle ilgili sorguları ad veya adres kullanarak girmesini bekliyorsanız Yer Ayrıntıları (Yeni) isteği kullanın. Sonuçların yalnızca belirli bir bölgede olması bekleniyorsa konum önceliği kullanın.
  Geocoding API'ye geri dönmenin en iyi olduğu diğer senaryolar şunlardır:
  • Kullanıcılar, bir bina içindeki belirli birimlerin veya dairelerin adresleri gibi alt tesis adreslerini girerken. Örneğin, Çekçe adres "Stroupežnického 3191/17, Praha" için Otomatik Tamamlama (Yeni) özelliğinde kısmi bir tahmin elde edilir.
  • New York City'de "23-30 29th St, Queens" veya Hawaii'deki Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti önekleri içeren adresleri giren kullanıcılar.

Konum önyargısı

location parametresi ve radius parametresi ileterek sonuçları belirli bir alana göre yönlendirin. Bu, Otomatik Tamamlama'ya (Yeni) tanımlanan alan içindeki sonuçları göstermeyi tercih etmesini söyler. Tanımlanan alanın dışındaki sonuçlar yine de gösterilebilir. Sonuçları filtreleyerek yalnızca belirli bir ülke içindeki yerleri göstermek için includedRegionCodes parametresini kullanabilirsiniz.

Konum kısıtlama

locationRestriction parametresini ileterek sonuçları belirli bir alanla sınırlayın.

Ayrıca, location ve radius parametreleriyle tanımlanan bölgeyle sonuçları kısıtlamak için locationRestriction parametresini ekleyebilirsiniz. Bu, Otomatik Tamamlama'ya (Yeni) yalnızca bu bölgedeki sonuçları döndürmesini söyler.

Deneyin.

API Gezgini, API ve API seçenekleri hakkında bilgi edinmek için örnek istekler göndermenize olanak tanır.

1. Sayfanın sağ tarafındaki API simgesini api seçin.

2. İsteğe bağlı olarak istek parametrelerini düzenleyin.

3. Yürüt düğmesini seçin. İletişim kutusunda, isteği göndermek için kullanmak istediğiniz hesabı seçin.

4. API Gezgini penceresini genişletmek için API Gezgini panelinde tam ekran simgesini fullscreen seçin.