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.

Autocomplete (New), girişin tam kelimeleri ve alt dizeleriyle eşleşerek yer adlarını, adresleri ve Plus Kodları çözebilir. Bu nedenle uygulamalar, kullanıcı yazarken sorgu göndererek anında yer ve sorgu tahminleri sağlayabilir.

Autocomplete (New) 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ş metin 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, Otomatik Tamamlama (Yeni) özelliğini, kısmi bir kullanıcı girişi ("Sicilian piz") içeren bir dizeyi giriş olarak kullanarak çağırırsınız ve arama alanını San Francisco, Kaliforniya ile sınırlarsınız. 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ıya sunularak amaçlanan yeri seçmesine 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ği gönderebilirsiniz.

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

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

Autocomplete (New) istekleri

Autocomplete (New) isteği, aşağıdaki biçimde bir URL'ye gönderilen 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 üstbilgilerde 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

Autocomplete (New), 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ıralı olarak içerir. Her yer bir placePrediction alanı, her sorgu ise bir queryPrediction alanı ile temsil edilir.
• 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şine daha yakın bir eşleşme sağlamak 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 tahmini hakkında ayrıntılı bilgi 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ş

Aranacak metin dizesi. Tam kelimeleri ve alt dizeleri, yer adlarını, adresleri ve Plus Code'ları belirtin. Autocomplete (New) hizmeti, bu dizeye göre eşleşme adayları döndürür ve sonuçları algılanan alaka düzeyine 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 üstbilgisini X-Goog-FieldMask 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 ise 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.

Varsayılan olarak API, 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 kısıtlayı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, (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.

Aşağıdaki durumlarda istek INVALID_REQUEST hatasıyla reddedilir:

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

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 değerine ayarlanırsa API yalnızca fiziksel işletme konumu olan işletmeleri döndürür.

includeQueryPredictions

true ise yanıt hem yer hem de sorgu tahminlerini içerir. Varsayılan değer false olduğundan yanıt yalnızca yer tahminlerini içerir.

includedRegionCodes

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

inputOffset

input içinde imleç konumunu gösteren sıfır tabanlı Unicode karakter ofseti. İmlecin konumu, döndürülen tahminleri etkileyebilir. Boş bırakılırsa 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 yerin yerel dilden languageCode diline çevirisi yoksa sonuçlar farklı 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. Hiçbiri 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.
  • Öncelikle input parametresindeki eşleşen terimler seçilir. Bu işlem sırasında, mümkünse languageCode parametresiyle belirtilen dil tercihine uygun adlar, aksi takdirde kullanıcı girişine en uygun adlar kullanılır.
  • Yer adları, input parametresindeki terimlerle eşleşecek şekilde alternatif adlar kullanılarak biçimlendirilebilir. Bu adlara, languageCode parametresiyle belirtilen dil dışındaki dillerde olan adlar da dahildir.
  • Açık adresler, yalnızca input parametresindeki terimlerle eşleşen terimler seçildikten sonra yerel dilde, mümkün olduğunda kullanıcı tarafından okunabilir bir alfabeyle biçimlendirilir.
  • Diğer tüm adresler, input parametresindeki terimlerle eşleşen terimler seçildikten sonra tercih edilen dilde döndürülür. Tercih edilen dilde bir 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 alanı belirtir. Bu konum, bir eğilim olarak kullanılır. Yani belirtilen konumun çevresindeki sonuçlar (belirtilen alanın dışındaki sonuçlar dahil) 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 görüntü alanı ya da daire olarak belirtin.

• 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, çapraz olarak karşılıklı iki low ve yüksek nokta olarak temsil edilen bir enlem-boylam görüntü alanıdır. Görüntü alanı, kapalı bir bölge olarak kabul edilir. Yani sınırını içerir. Enlem sınırları -90 ile 90 derece arasında (bu değerler dahil), boylam sınırları ise -180 ile 180 derece arasında (bu değerler dahil) olmalıdır:

  • low = high ise görüntü alanı bu tek 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ştur.

  Hem low hem de high doldurulmalıdır ve temsil edilen kutu boş olamaz. Boş bir görüntü alanı hataya neden olur.

  Örneğin, bu görüntü alanı New York'u 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. ccTLD ("üst düzey alan") iki karakterli değeri olarak belirtilir. Ç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) 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 farklılık gösterir. 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. Parametre, geçerli yasaya göre sonuçları etkileyebilir.

regionCode ayarını yaptığınızda, bu bölgedeki tahminler öneri metninden ülke adını çıkarabilir. Bu durumda structuredFormat.secondaryText mevcut olmayabilir. Bu nedenle, uygulamanızın secondaryText parametresinin tanımlanmadığı veya eksik olduğu durumları işlediğinden emin olun.

sessionToken

Oturum jetonları, Autocomplete (New) çağrılarını "oturum" olarak izleyen, kullanıcı tarafından oluşturulan dizelerdir. Otomatik Tamamlama (Yeni), faturalandırma amacıyla bir kullanıcı otomatik tamamlama aramasının sorgu ve seçim aşamalarını 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çme

Otomatik tamamlama (yeni) örnekleri

locationRestriction kullanarak aramayı bir alanla kısıtlama

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 merkezli 5.000 metre yarıçaplı bir daire ile sınırlamak için locationRestriction kullanılmıştır:

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 kısıtlamak için locationRestriction parametresini de kullanabilirsiniz. Aşağıdaki örnekte, istek San Francisco'nun şehir merkeziyle sınırlandırılmıştır:

  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 bölgeye yönlendirme

locationBias ile konum, bir eğilim olarak kullanılır. Bu, 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. Aşağıdaki örnekte, isteği San Francisco ş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 metrelik 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üntü alanına yönlendirmek için locationBias parametresini 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üntü alanındaki arama sonuçları yanıtta görünse de bazı sonuçlar, yanlılık nedeniyle tanımlanan sınırların dışındadı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

Tablo A, Tablo B'den veya yalnızca (regions) ya da yalnızca (cities)'dan 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" değerine sahip bir input dizesi belirtiyor ve sonuçları "sporting_goods_store" türündeki işletmelerle 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 atlarsanız sonuçlar, "athletic_field" gibi istemediğiniz türde işletmeleri 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ıda 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 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 Text Search (New) isteği gönderebilirsiniz.

Kaynak kullan

Bu örnekte, isteğe enlem ve boylam koordinatları olarak origin değerini ekleyin. origin parametresini eklediğinizde Otomatik Tamamlama (Yeni), yanıta distanceMeters alanını ekler. Bu alan, origin ile hedef arasındaki doğrusal mesafeyi içerir. Bu örnekte, başlangıç noktası San Francisco'nun merkezi olarak ayarlanmıştı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
      }
    }
  ]
}

İleride 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ıtta yerle ilgili ayrıntılar var ancak açılış tarihi yok.

{
  "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, isteğe origin dahil edilmiş olsa bile yanıt gövdesinde distanceMeters eksik oluyor. Bu durum, aşağıdaki senaryolarda gerçekleşebilir:

• 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 mesafeyi sıfır olarak 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, Maps JavaScript API Otomatik Tamamlama (Yeni) widget'ını, Android için Yerler SDK'sı Otomatik Tamamlama (Yeni) widget'ını veya iOS için Yerler SDK'sı Otomatik Tamamlama (Yeni) widget'ını kullanmaktır.
• Temel Otomatik Tamamlama (Yeni) 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

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

Gelişmiş maliyet optimizasyonu

SKU: Autocomplete Request fiyatlandırmasına erişmek ve Yer Ayrıntıları (Yeni) yerine seçilen yerle ilgili Geocoding API sonuçları istemek için Autocomplete'in (Yeni) programatik uygulamasını kullanabilirsiniz. Geocoding API ile eşlenen istek başına fiyatlandırma, aşağıdaki koşulların her ikisi de karşılandığında oturum başına (oturum tabanlı) fiyatlandırmadan daha uygun maliyetlidir:

• Yalnızca kullanıcının seçtiği yerin enlem ve boylamına veya adresine ihtiyacınız varsa Geocoding API, bu bilgileri Yer Ayrıntıları (Yeni) çağrısından daha düşük bir ücret karşılığında 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ırmadan daha uygun maliyetli olabilir.

Geocoding API, Autocomplete (New) kullanımınızın performansına bağlı olarak uygulamanız için Yer Ayrıntıları (New)'dan daha uygun maliyetli bir seçenek olabilir. Her uygulamanın Autocomplete (New) verimliliği; kullanıcıların ne girdiğine, uygulamanın nerede kullanıldığına ve performans optimizasyonuyla ilgili en iyi uygulamaların hayata geçirilip geçirilmediğine bağlı olarak değişir.

Tablo için ortalama istek sayısını bulmak istiyorsanız uygulamanızda bir Otomatik Tamamlama (Yeni) tahminini seçmeden önce kullanıcının ortalama kaç karakter yazdığını analiz edin.

Yer Ayrıntıları (Yeni) ile oturuma dayalı Otomatik Tamamlama (Yeni)

Oturuma dayalı Otomatik Tamamlama (Yeni) özelliğini Yer Ayrıntıları (Yeni) ile kullanın.
Uygulamanız yer adı, işletme durumu veya çalışma saatleri gibi Yer Ayrıntıları (Yeni) bilgilerini gerektirdiğinden Otomatik Tamamlama (Yeni) uygulamanızda, istediğiniz yer veri alanlarına bağlı olarak oturum başına bir oturum jetonu (programatik olarak veya JavaScript, Android ya da iOS widget'larına yerleşik olarak) ve geçerli Places SKU'ları kullanılmalıdır.¹

Widget uygulaması
Oturum yönetimi; JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Buna, seçilen tahminle ilgili hem Otomatik Tamamlama (Yeni) istekleri hem de Yer Ayrıntıları (Yeni) isteği dahildir. Yalnızca ihtiyacınız olan Autocomplete (New) veri alanlarını istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programatik uygulama
Otomatik Tamamlama (Yeni) isteklerinizde oturum jetonu kullanın. Seçilen tahminle ilgili Yer Ayrıntıları (Yeni) isteğinde bulunurken aşağıdaki parametreleri ekleyin:

1. Otomatik Tamamlama (Yeni) yanıtındaki yer kimliği
2. Autocomplete (New) isteğinde kullanılan oturum jetonu
3. İhtiyacınız olan Otomatik Tamamlama (Yeni) veri alanlarını belirten fields parametresi

Geocoding API ile istek başına Autocomplete (New)

Autocomplete'i (New) oturum jetonları olmadan programatik olarak uygulayın ve seçilen yer tahmini için Geocoding API'yi çağırın.
Geocoding API, adresleri ve enlem/boylam koordinatlarını sağlar. Dört Autocomplete Requests isteği ve seçilen yer tahminiyle ilgili bir Geocoding API çağrısı yapmanın maliyeti, oturum başına Autocomplete (New) maliyetinden daha düşüktür.¹

Kullanıcılarınızın aradıkları tahmini daha az karakterle almalarına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.

Yalnızca adres uygulamaları için oturuma dayalı Autocomplete (New)

Oturuma dayalı Otomatik Tamamlama (Yeni) özelliğini Yer Ayrıntıları (Yeni) ile kullanın.
Kullanıcı bir Otomatik Tamamlama (Yeni) tahminini seçmeden önce yapmayı beklediğiniz ortalama istek sayısı, oturum başına fiyatlandırma maliyetini aştığından Otomatik Tamamlama (Yeni) uygulamanızda hem Otomatik Tamamlama (Yeni) istekleri hem de ilişkili Yer Ayrıntıları (Yeni) isteği için oturum jetonu kullanılmalıdır. oturum başına. ¹

Widget uygulaması
Oturum yönetimi; JavaScript, Android veya iOS widget'larına otomatik olarak yerleştirilir. Buna, seçilen tahminle ilgili hem Otomatik Tamamlama (Yeni) istekleri hem de Yer Ayrıntıları (Yeni) isteği dahildir. Yalnızca ihtiyacınız olan alanları istediğinizden emin olmak için fields parametresini belirttiğinizden emin olun.

Programatik uygulama
Autocomplete (New) isteklerinizde oturum jetonu kullanın. Seçilen tahminle ilgili Yer Ayrıntıları (Yeni) isteğinde bulunurken aşağıdaki parametreleri ekleyin:

1. Otomatik Tamamlama (Yeni) yanıtındaki yer kimliği
2. Autocomplete (New) isteğinde kullanılan oturum jetonu
3. Adres ve geometri gibi alanları belirten fields parametresi

Autocomplete (New) isteklerini geciktirmeyi düşünün
Uygulamanızın daha az istek göndermesi için Autocomplete (New) isteğini kullanıcı ilk üç veya dört karakteri yazana kadar geciktirme gibi stratejiler kullanabilirsiniz. Örneğin, kullanıcı üçüncü karakteri yazdıktan sonra her karakter için Autocomplete (New) istekleri yapılması, kullanıcı yedi karakter yazıp ardından bir Geocoding API isteği yaptığınız bir tahmini seçerse toplam maliyetin 4 Autocomplete (New) istek başına + Geocoding için olacağı anlamına gelir.¹

İstekleri geciktirmek ortalama programatik istek sayınızı dörtten az yapabiliyorsa Geocoding API ile yüksek performanslı Autocomplete (New) uygulamasıyla ilgili kılavuzu takip edebilirsiniz. İsteklerin geciktirilmesinin, her yeni tuş vuruşunda tahminleri görmeyi bekleyen kullanıcı tarafından gecikme olarak algılanabileceğini unutmayın.

Kullanıcılarınızın aradıkları tahmini daha az karakterle bulmalarına yardımcı olmak için performansla ilgili en iyi uygulamalardan yararlanabilirsiniz.

Performansla ilgili en iyi uygulamalar

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

• Otomatik Tamamlama (Yeni) uygulamanıza ülkeye özgü kısıtlamalar, konum ağırlığı ve (programatik uygulamalar için) dil tercihleri ekleyin. Widget'lar, dil tercihlerini kullanıcının tarayıcısından veya mobil cihazından aldığı için widget'larda dil tercihine gerek yoktur.
• Autocomplete (New) ile birlikte bir harita varsa konumu harita görüntü alanına göre yönlendirebilirsiniz.
• Kullanıcı, Autocomplete (New) tahminlerinden birini seçmediğinde (genellikle bu tahminlerden hiçbiri istenen sonuç adresi olmadığı için) 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 çağrısında orijinal kullanıcı girişini yeniden kullanın.
  • Kullanıcının belirli bir yer için ad veya adresle sorgu girmesini bekliyorsanız Yer Ayrıntıları (Yeni) isteği kullanın. Sonuçların yalnızca belirli bir bölgede gösterilmesi bekleniyorsa konum ağırlığı kullanın.
  Geocoding API'ye başvurmanın en iyi seçenek olduğu diğer senaryolar şunlardır:
  • Kullanıcılar, bir binadaki belirli birimlerin veya dairelerin adresleri gibi alt tesis adreslerini giriyor. Örneğin, Çekçe "Stroupežnického 3191/17, Praha" adresi, Otomatik Tamamlama (Yeni) özelliğinde kısmi bir tahmin döndürür.
  • Kullanıcılar, New York'ta "23-30 29th St, Queens" veya Hawaii'nin Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleri içeren adresler giriyor.

Konuma göre önceliklendirme

location parametresi ve radius parametresi ileterek sonuçları belirli bir alana göre önceliklendirin. 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 gösterilmeye devam edebilir. Sonuçları yalnızca belirtilen bir ülkedeki yerleri gösterecek şekilde filtrelemek için includedRegionCodes parametresini kullanabilirsiniz.

Konum kısıtlama

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

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

Deneyin.

API Gezgini, API'yi ve API seçeneklerini tanıyabilmeniz 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. Execute (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 panelinde, API Gezgini penceresini genişletmek için tam ekran simgesini fullscreen seçin.