Otomatik Tamamla (Yeni)

Giriş

Autocomplete (Yeni), bir HTTP isteğine yanıt olarak yer tahminleri ve sorgu tahminleri döndüren bir web hizmetidir. İstekle birlikte, 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 artı kodlarını çözebilir. Bu nedenle uygulamalar, kullanıcı yazarken anında yer ve sorgu tahminleri sağlamak için sorgu gönderebilir.

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ıtına sorgu tahminleri eklemek için includeQueryPredictions istek parametresini kullanın.

Örneğin, giriş olarak kısmi kullanıcı girişi içeren bir dize ("Sicilian piz") kullanarak Otomatik Tamamlama (Yeni) işlevini çağırıyorsunuz ve arama alanı Kaliforniya, San Francisco ile sınırlı. 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ının istediği 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ğinde bulunabilirsiniz.

Yanıtta, arama dizesi ve arama alanıyla eşleşen sorgu tahminlerinin listesi de yer alabilir. Örneğin, "Sicilian Pizza & Pasta". 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 Metin Arama (Yeni)'ya giriş olarak kullanın.

API Gezgini, API ve API seçenekleri hakkında bilgi edinmek için canlı isteklerde bulunmanıza olanak tanır:

Otomatik Tamamlama (Yeni) istekleri

Otomatik Tamamlama (Yeni) isteği, aşağıdaki biçimde bir URL'ye gönderilen HTTP POST isteğidir:

https://places.googleapis.com/v1/places:autocomplete

JSON istek gövdesindeki veya üstbilgilerdeki 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 temsil edilir.
• placePrediction alanı, yer kimliği ve metin açıklaması da dahil olmak üzere tek bir yer tahminiyle ilgili ayrıntılı bilgileri içerir.
• 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 artı kodları 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

  Yanıt alan maskesi oluşturarak yanıtta döndürülecek alanların listesini belirtin. HTTP üst bilgisini 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 * öğesini kullanın.

    X-Goog-FieldMask: *

• 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 input parametresine göre tüm yerleri döndürür. Bu işlem, yerle ilişkili birincil tür değerinden bağımsız olarak gerçekleştirilir. includedPrimaryTypes parametresini ileterek sonuçları belirli bir birincil tür veya birincil türlerle kısıtlayın.

  Bu parametreyi kullanarak A Tablosu veya B Tablosu'ndan en fazla beş tür değeri belirtebilirsiniz. Bir yerin yanıtta yer alması 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ü, mahalleler ve posta kodları gibi alanlar veya bölümler için koleksiyon filtreleri. (cities) türü koleksiyonu, 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 belirtilmiş.
  • Tanınmayan türler belirtilir.

• includePureServiceAreaBusinesses

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

• includeQueryPredictions

  true ise yanıtta hem yer hem de sorgu tahminleri yer alır. Varsayılan değer false'dır. Bu durumda, yanıtta yalnızca yer tahminleri yer alır.

• includedRegionCodes

  Yalnızca belirtilen bölgeler listesindeki sonuçları ekleyin. Bu bölgeler, en fazla 15 ccTLD ("üst düzey alan") iki karakterli değer dizisi 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 öğ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 uzaklığı. İmleç konumu, hangi tahminlerin döndürüleceğini etkileyebilir. Boş bırakılırsa varsayılan olarak input uzunluğu kullanılır.

• languageCode

  Sonuçların döndürü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 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.
  • API, hem kullanıcı hem de yerel halk tarafından okunabilir bir sokak adresi sağlamaya çalışırken aynı zamanda kullanıcı girişini de yansıtır. 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.
    • Sokak adresleri, mümkün olduğunda kullanıcının okuyabileceği bir yazı türünde yerel dilde 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, 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 bir alanı belirtir. Belirtilen alanın dışındaki sonuçlar döndürülmez.

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

  • Bir daire, merkez noktası ve metre cinsinden yarıçap ile tanımlanır. Yarıçap 0,0 ile 50000,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üntü alanıdır. Görüntü alanı, sınırını da içeren kapalı bir bölge olarak kabul edilir. 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ı 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 gösterilen 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 kapsar:

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

• kaynak

  Hedefe olan kuş uçuşu mesafenin hesaplanacağı başlangıç noktası (distanceMeters olarak döndürülür). Bu değer atlanırsa kuş uçuşu mesafe 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. Çoğu ccTLD kodu, ISO 3166-1 kodlarıyla aynıdır. Ancak bazı önemli istisnalar vardı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 yanlı olabilir. Google, regionCode ayarının kullanıcının bölgesel tercihine göre belirlenmesini ö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.

• 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ı otomatik tamamlama aramasının sorgu ve seçim aşamalarını faturalandırma amacıyla ayrı bir oturumda gruplandırmak için oturum jetonlarını kullanır. Daha fazla bilgi için Oturum jetonları 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'nun merkezinde 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 simgesini de kullanabilirsiniz. Aşağıdaki örnekte istek, San Francisco ş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 alana yönlendirme

locationBias ile konum, bir önyargı olarak işlev görür. Bu nedenle, belirtilen konumun çevresindeki sonuçlar (belirtilen alanın dışındaki sonuçlar dahil) döndürülebilir. 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 metre yarıçapını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 simgesini de kullanabilirsiniz. Aşağıdaki örnekte istek, San Francisco ş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 özelliğini kullanma

includedPrimaryTypes parametresini kullanarak A Tablosu, B Tablosu veya yalnızca (regions) ya da yalnızca (cities)'dan en fazla beş tür değeri belirtebilirsiniz. Bir yerin yanıtta yer alması için belirtilen birincil tür değerlerinden biriyle eşleşmesi gerekir.

Aşağıdaki örnekte, input dizesini "Futbol" olarak belirtiyor ve sonuçları "sporting_goods_store" türündeki kuruluşlarla sınırlandırmak 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 kuruluşları içerebilir.

Sorgu tahmini isteğinde bulunma

Sorgu tahminleri varsayılan olarak döndürülmez. Yanıtı sorgu tahminleriyle zenginleştirmek 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.

Kaynağı kullanma

Bu örnekte, enlem ve boylam koordinatları olarak isteğe origin değerini ekleyin. origin eklediğinizde, Otomatik Tamamlama (Yeni), yanıta origin ile hedef arasındaki kuş uçuşu mesafeyi 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ıtta artık distanceMeters yer alıyor:

{
  "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
      }
    }
  ]
}

Yanıtla ilgili mesafe bilgisi eksik

Bazı durumlarda, istekte origin yer alsa bile yanıt gövdesinde distanceMeters 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 kısa mesafedeki tahminler için geçerlidir.

Ayrıştırılmış bir nesneden distanceMeters alanını okumaya çalışan istemci kitaplıkları, değeri 0 olan 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.
• Başlangıçtan itibaren temel Otomatik Tamamlama (Yeni) veri alanlarını anlayın.
• Konum tercihi ve konum kısıtlama alanları isteğe bağlıdır ancak otomatik tamamlama performansını önemli ölçüde etkileyebilir.
• API hata döndürürse uygulamanızın sorunsuz bir şekilde çalışmaya devam etmesini sağlamak için hata işlemeyi kullanın.
• Uygulamanızın seçim yapılmadığı durumları yönettiğinden ve kullanıcılara devam etme olanağı sunduğundan emin olun.

Maliyet optimizasyonu ile ilgili en iyi uygulamalar

Temel maliyet optimizasyonu

Otomatik Tamamlama (Yeni) hizmetinin kullanım 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

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

• Yalnızca kullanıcının seçtiği yerin enlemi/boylamı veya adresi gerekiyorsa Geocoding API, bu bilgileri Place Details (New) çağrısından daha az 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ırmaya kıyasla daha uygun maliyetli olabilir.

Uygulamanız, seçilen tahminin adresi ve enlem/boylamı dışında herhangi bir 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 ülke kısıtlamaları, konum önyargısı ve (programatik uygulamalar için) dil tercihi ekleyin. Dil tercihi, kullanıcının tarayıcısından veya mobil cihazından dil tercihlerini aldıkları için widget'larda gerekli değildir.
• Otomatik Tamamlama (Yeni) özelliğine harita eşlik ediyorsa harita görüntü alanına göre konumu önyargılı hale getirebilirsiniz.
• 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 gireceğini düşünüyorsanız Coğrafi Kodlama API'sine yapılan bir çağrıda orijinal kullanıcı girişini yeniden kullanın.
  • Kullanıcının belirli bir yerle ilgili sorguları ada veya adrese göre girmesini bekliyorsanız Yer Ayrıntıları (Yeni) isteğini kullanın. Sonuçların yalnızca belirli bir bölgede beklenmesi durumunda konum önyargısı 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, "Stroupežnického 3191/17, Praha" Çekçe adresi, otomatik tamamlama (yeni) özelliğinde kısmi bir tahminle sonuçlanır.
  • New York'ta "23-30 29th St, Queens" veya Hawaii'deki Kauai adasında "47-380 Kamehameha Hwy, Kaneohe" gibi yol segmenti ön ekleri içeren adresleri giren kullanıcılar.

Konum önyargısı

location parametresi ve radius parametresi ileterek sonuçları belirli bir alana yönlendirin. Bu, otomatik tamamlama (yeni) özelliğine, tanımlanan alan içindeki sonuçları göstermeyi tercih etmesini bildirir. Tanımlanan alanın dışındaki sonuçlar gösterilmeye devam edebilir. Sonuçları yalnızca belirtilen bir ülke içindeki yerleri gösterecek şekilde filtrelemek için components parametresini kullanabilirsiniz.

Konum kısıtlama

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

Ayrıca, location ve radius parametresiyle tanımlanan bölgeyle sonuçları kısıtlamak için locationRestriction parametresini ekleyebilirsiniz. Bu, Otomatik Tamamlama (Yeni) özelliğine yalnızca bu bölgedeki sonuçları döndürmesi talimatını verir.

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.