Pelengkapan Otomatis (Baru)

Pengantar

Autocomplete (New) adalah layanan web yang menampilkan prediksi tempat dan prediksi kueri sebagai respons terhadap permintaan HTTP. Dalam permintaan, tentukan string penelusuran teks dan batas geografis yang mengontrol area penelusuran.

Autocomplete (Baru) dapat mencocokkan kata dan substring lengkap dari input, yang me-resolve nama tempat, alamat, dan Plus Codes. Oleh karena itu, aplikasi dapat mengirimkan kueri saat pengguna mengetik, untuk memberikan prediksi tempat dan kueri secara real time.

Respons dari Autocomplete (Baru) dapat berisi dua jenis prediksi:

• Prediksi tempat: Tempat, seperti bisnis, alamat, dan lokasi menarik, berdasarkan string teks input dan area penelusuran yang ditentukan. Prediksi tempat ditampilkan secara default.
• Prediksi kueri: String kueri yang cocok dengan string teks input dan area penelusuran. Prediksi kueri tidak ditampilkan secara default. Gunakan parameter permintaan includeQueryPredictions untuk menambahkan prediksi kueri ke respons.

Misalnya, Anda memanggil Autocomplete (Baru) menggunakan sebagai input string yang berisi input pengguna parsial, "Sicilian piz", dengan area penelusuran dibatasi ke San Francisco, CA. Respons kemudian berisi daftar prediksi tempat yang cocok dengan string penelusuran dan area penelusuran, seperti restoran bernama "Sicilian Pizza Kitchen", beserta detail tentang tempat tersebut.

Prediksi tempat yang ditampilkan dirancang untuk ditampilkan kepada pengguna guna membantu mereka memilih tempat yang diinginkan. Anda dapat membuat permintaan Place Details (Baru) untuk mendapatkan informasi selengkapnya tentang prediksi tempat yang ditampilkan.

Respons juga dapat berisi daftar prediksi kueri yang cocok dengan string penelusuran dan area penelusuran, seperti "Sicilian Pizza & Pasta". Setiap prediksi kueri dalam respons mencakup kolom text yang berisi string Text Search yang direkomendasikan. Gunakan string tersebut sebagai input ke Text Search (Baru) untuk melakukan penelusuran yang lebih mendetail.

APIs Explorer memungkinkan Anda membuat permintaan langsung sehingga Anda dapat memahami API dan opsi API:

Permintaan Pelengkapan Otomatis (Baru)

Permintaan Autocomplete (New) adalah permintaan POST HTTP ke URL dalam bentuk:

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

Teruskan semua parameter dalam isi permintaan JSON atau di header sebagai bagian dari permintaan POST. Contoh:

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

Parameter yang didukung

Tentang respons

Autocomplete (Baru) menampilkan objek JSON sebagai respons. Dalam respons:

• Array suggestions berisi semua tempat dan kueri yang diprediksi secara berurutan berdasarkan relevansinya yang terlihat. Setiap tempat diwakili oleh kolom placePrediction dan setiap kueri diwakili oleh kolom queryPrediction.
• Kolom placePrediction berisi informasi mendetail tentang satu prediksi tempat, termasuk ID tempat dan deskripsi teks.
  • Agar lebih cocok dengan input pengguna sebagaimana diberikan dalam parameter input, deskripsi teks prediksi tempat dapat mencakup nama alternatif untuk tempat, jalan, dan komponen alamat lainnya. Nama alternatif ini mungkin berbeda dengan nama yang ditampilkan di kolom displayName dan alamat hasil Place Details untuk ID tempat yang sama.
  • Dalam konteks ini, nama alternatif untuk beberapa tempat mungkin dalam bahasa yang berbeda dari yang diharapkan berdasarkan parameter languageCode, bergantung pada nama mana yang paling cocok dengan input pengguna.
• Kolom queryPrediction berisi informasi mendetail tentang satu prediksi kueri.

Objek JSON lengkap dalam bentuk:

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

Parameter yang diperlukan

• input

  String teks yang akan ditelusuri. Tentukan kata dan substring lengkap, nama tempat, alamat, dan Plus Codes. Layanan Pelengkapan Otomatis (Baru) menampilkan bakal hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.

Parameter opsional

• FieldMask

  Tentukan daftar kolom yang akan ditampilkan dalam respons dengan membuat mask kolom respons. Teruskan mask kolom respons ke metode menggunakan header HTTP X-Goog-FieldMask.

  Tentukan daftar kolom saran yang dipisahkan koma yang akan ditampilkan. Misalnya, untuk mengambil suggestions.placePrediction.text.text dan suggestions.queryPrediction.text.text saran.

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

  Gunakan * untuk mengambil semua kolom.

    X-Goog-FieldMask: *

• includeFutureOpeningBusinesses

  Jika true, menampilkan bisnis yang diharapkan akan buka pada masa mendatang. Nilai defaultnya adalah false.

• includedPrimaryTypes

  Tempat hanya dapat memiliki satu jenis utama dari jenis yang tercantum dalam Tabel A atau Tabel B. Misalnya, jenis utama mungkin berupa "mexican_restaurant" atau "steak_house".

  Secara default, API menampilkan semua tempat berdasarkan parameter input, terlepas dari nilai jenis utama yang terkait dengan tempat tersebut. Batasi hasil agar memiliki jenis utama atau jenis utama tertentu dengan meneruskan parameter includedPrimaryTypes.

  Gunakan parameter ini untuk menentukan hingga lima nilai jenis dari Tabel A atau Tabel B. Tempat harus cocok dengan salah satu nilai jenis utama yang ditentukan agar disertakan dalam respons.

  Parameter ini juga dapat menyertakan salah satu dari (regions) atau (cities). Kumpulan jenis (regions) memfilter area atau divisi, seperti kawasan dan kode pos. Kumpulan jenis (cities) memfilter tempat yang diidentifikasi Google sebagai kota.

  Permintaan ditolak dengan error INVALID_REQUEST jika:

  • Lebih dari lima jenis ditentukan.
  • Jenis apa pun ditentukan selain (cities) atau (regions).
  • Jenis yang tidak dikenal akan ditentukan.

• includePureServiceAreaBusinesses

  Jika ditetapkan ke true, respons akan menyertakan bisnis yang mengunjungi atau mengirimkan langsung ke pelanggan, tetapi tidak memiliki lokasi bisnis fisik. Jika disetel ke false, API hanya menampilkan bisnis dengan lokasi bisnis fisik.

• includeQueryPredictions

  Jika true, respons akan menyertakan prediksi tempat dan kueri. Nilai defaultnya adalah false, yang berarti respons hanya mencakup prediksi tempat.

• includedRegionCodes

  Hanya menyertakan hasil dari daftar wilayah yang ditentukan, yang ditentukan sebagai array hingga 15 nilai dua karakter ccTLD ("domain level teratas"). Jika tidak disertakan, tidak ada batasan yang diterapkan pada respons. Misalnya, untuk membatasi wilayah ke Jerman dan Prancis:

      "includedRegionCodes": ["de", "fr"]

  Jika Anda menentukan locationRestriction dan includedRegionCodes, hasilnya terletak di area persimpangan kedua setelan.

• inputOffset

  Offset karakter Unicode berbasis nol yang menunjukkan posisi kursor di input. Posisi kursor dapat memengaruhi prediksi yang ditampilkan. Jika kosong, nilai defaultnya adalah panjang input.

• languageCode

  Bahasa pilihan untuk menampilkan hasil. Hasilnya mungkin dalam bahasa campuran jika bahasa yang digunakan di input berbeda dengan nilai yang ditentukan oleh languageCode, atau jika tempat yang ditampilkan tidak memiliki terjemahan dari bahasa lokal ke languageCode.

  • Anda harus menggunakan kode bahasa BCP-47 IETF untuk menentukan bahasa pilihan.
  • Jika languageCode tidak diberikan, API akan menggunakan nilai yang ditentukan di header Accept-Language. Jika tidak ada yang ditentukan, defaultnya adalah en. Jika Anda menentukan kode bahasa yang tidak valid, API akan menampilkan error INVALID_ARGUMENT.
  • Bahasa pilihan memiliki sedikit pengaruh pada kumpulan hasil yang dipilih API untuk ditampilkan, dan urutan penampilannya. Hal ini juga memengaruhi kemampuan API untuk mengoreksi kesalahan ejaan.
  • Prediksi tempat diformat secara berbeda, bergantung pada input pengguna dalam setiap permintaan.
    • Istilah yang cocok dalam parameter input dipilih terlebih dahulu, menggunakan nama yang selaras dengan preferensi bahasa yang ditunjukkan oleh parameter languageCode jika tersedia, atau menggunakan nama yang paling cocok dengan input pengguna.
    • Nama tempat dapat diformat menggunakan nama alternatif agar sesuai dengan istilah dalam parameter input, termasuk nama dalam bahasa selain bahasa yang ditunjukkan oleh parameter languageCode.
    • Alamat jalan diformat dalam bahasa lokal, dalam skrip yang dapat dibaca oleh pengguna jika memungkinkan, hanya setelah istilah yang cocok dipilih agar sesuai dengan istilah dalam parameter input.
    • Semua alamat lainnya ditampilkan dalam bahasa pilihan, setelah istilah yang cocok dipilih agar sesuai dengan istilah dalam parameter input. Jika nama tidak tersedia dalam bahasa pilihan, API akan menggunakan kecocokan terdekat.

• locationBias atau locationRestriction

  Anda dapat menentukan locationBias atau locationRestriction, tetapi tidak keduanya, untuk menentukan area penelusuran. Anggap locationRestriction sebagai penentu wilayah tempat hasil harus berada, dan locationBias sebagai penentu wilayah tempat hasil harus berada di dekatnya, tetapi dapat berada di luar area tersebut.

  • locationBias

    Menentukan area yang akan ditelusuri. Lokasi ini berfungsi sebagai bias yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan.

  • locationRestriction

    Menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak ditampilkan.

  Tentukan wilayah locationBias atau locationRestriction sebagai Area Pandang persegi panjang atau sebagai lingkaran.

  • Lingkaran ditentukan oleh titik tengah dan radius dalam meter. Radius harus antara 0,0 dan 50000,0, inklusif. Nilai defaultnya adalah 0,0. Untuk locationRestriction, Anda harus menetapkan radius ke nilai yang lebih besar dari 0,0. Jika tidak, permintaan tidak akan menampilkan hasil.

    Contoh:

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

  • Persegi panjang adalah area tampilan garis lintang-bujur, yang ditampilkan sebagai dua titik rendah dan tinggi yang berlawanan secara diagonal low. Area tampilan dianggap sebagai area tertutup, yang berarti area tersebut mencakup batasnya. Batas lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus berkisar antara -180 hingga 180 derajat inklusif:

    • Jika low = high, area pandang terdiri dari satu titik tersebut.
    • Jika low.longitude > high.longitude, rentang bujur akan dibalik (area pandang melintasi garis bujur 180 derajat).
    • Jika low.longitude = -180 derajat dan high.longitude = 180 derajat, area pandang mencakup semua bujur.
    • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur kosong.

    low dan high harus diisi, dan kotak yang diwakili tidak boleh kosong. Area pandang kosong akan menghasilkan error.

    Misalnya, area tampilan ini sepenuhnya mencakup New York City:

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

• asal

  Titik asal untuk menghitung jarak garis lurus ke tujuan (ditampilkan sebagai distanceMeters). Jika nilai ini tidak dicantumkan, jarak garis lurus tidak akan ditampilkan. Harus ditentukan sebagai koordinat lintang dan bujur:

  "origin": {
      "latitude": 40.477398,
      "longitude": -74.259087
  }

• regionCode

  Kode wilayah yang digunakan untuk memformat respons, yang ditentukan sebagai nilai dua karakter ccTLD ("domain level teratas"). Sebagian besar kode ccTLD identik dengan kode ISO 3166-1, dengan beberapa pengecualian. Misalnya, ccTLD Inggris Raya adalah "uk" (.co.uk), sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "Kerajaan Bersatu Britania Raya dan Irlandia Utara").

  Saran juga bias berdasarkan kode wilayah. Google merekomendasikan untuk menetapkan regionCode sesuai dengan preferensi regional pengguna.

  Jika Anda menentukan kode wilayah yang tidak valid, API akan menampilkan error INVALID_ARGUMENT. Parameter dapat memengaruhi hasil berdasarkan hukum yang berlaku.

• sessionToken

  Token sesi adalah string yang dibuat pengguna yang melacak panggilan Autocomplete (Baru) sebagai "sesi". Autocomplete (Baru) menggunakan token sesi untuk mengelompokkan fase kueri dan pemilihan dari penelusuran pelengkapan otomatis pengguna ke dalam sesi terpisah untuk tujuan penagihan. Untuk mengetahui informasi selengkapnya, lihat Token sesi.

Memilih parameter untuk membiaskan hasil

Contoh Pelengkapan Otomatis (Baru)

Membatasi penelusuran ke suatu area menggunakan locationRestriction

locationRestriction menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak ditampilkan. Dalam contoh berikut, Anda menggunakan locationRestriction untuk membatasi permintaan ke lingkaran dengan radius 5.000 meter yang berpusat di San Francisco:

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

Semua hasil dari dalam area yang ditentukan terdapat dalam array suggestions:

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

Anda juga dapat menggunakan locationRestriction untuk membatasi penelusuran ke Viewport berbentuk persegi panjang. Contoh berikut membatasi permintaan ke pusat kota San Francisco:

  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

Hasilnya ada dalam array suggestions:

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

Membias penelusuran ke area tertentu menggunakan locationBias

Dengan locationBias, lokasi berfungsi sebagai bias yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan. Pada contoh berikut, Anda membiaskan permintaan ke pusat kota San Francisco:

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

Hasilnya kini berisi lebih banyak item, termasuk hasil di luar radius 5.000 meter:

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

Anda juga dapat menggunakan locationBias untuk membiaskan penelusuran ke Area pandang persegi panjang. Contoh berikut membatasi permintaan ke pusat kota San Francisco:

  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

Meskipun hasil penelusuran dalam area pandang persegi panjang muncul dalam respons, beberapa hasil berada di luar batas yang ditentukan, karena adanya bias. Hasil juga terdapat dalam array suggestions:

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

Menggunakan includedPrimaryTypes

Gunakan parameter includedPrimaryTypes untuk menentukan hingga lima nilai jenis dari Tabel A, Tabel B, atau hanya (regions), atau hanya (cities). Tempat harus cocok dengan salah satu nilai jenis utama yang ditentukan agar disertakan dalam respons.

Dalam contoh berikut, Anda menentukan string input "Soccer" dan menggunakan parameter includedPrimaryTypes untuk membatasi hasil ke tempat jenis "sporting_goods_store":

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

Jika Anda menghapus parameter includedPrimaryTypes, hasil dapat mencakup tempat dengan jenis yang tidak Anda inginkan, seperti "athletic_field".

Meminta prediksi kueri

Prediksi kueri tidak ditampilkan secara default. Gunakan parameter permintaan includeQueryPredictions untuk menambahkan prediksi kueri ke respons. Contoh:

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

Array suggestions kini berisi prediksi tempat dan prediksi kueri seperti yang ditunjukkan di atas dalam Tentang respons. Setiap prediksi kueri mencakup kolom text yang berisi string penelusuran teks yang direkomendasikan. Anda dapat membuat permintaan Text Search (Baru) untuk mendapatkan informasi selengkapnya tentang prediksi kueri yang ditampilkan.

Menggunakan asal

Dalam contoh ini, sertakan origin dalam permintaan sebagai koordinat lintang dan bujur. Jika Anda menyertakan origin, Autocomplete (New) akan menyertakan kolom distanceMeters dalam respons yang berisi jarak garis lurus dari origin ke tujuan. Contoh ini menetapkan origin ke pusat San Francisco:

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

Respons kini menyertakan distanceMeters:

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

Menemukan bisnis yang akan dibuka pada masa mendatang

Contoh berikut menunjukkan permintaan Pelengkapan Otomatis (Baru) untuk bisnis yang akan buka di masa mendatang di New Meadows, Idaho:

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"

Respons mencakup detail tentang tempat, tetapi tidak mencakup tanggal pembukaan.

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

Jarak tidak ada dalam respons

Dalam kasus tertentu, distanceMeters tidak ada dalam isi respons, meskipun origin disertakan dalam permintaan. Hal ini dapat terjadi dalam skenario berikut:

• distanceMeters tidak disertakan untuk prediksi route.
• distanceMeters tidak disertakan jika nilainya adalah 0, yang merupakan kasus untuk prediksi yang berjarak kurang dari 1 meter dari lokasi origin yang diberikan.

Library klien yang mencoba membaca kolom distanceMeters dari objek yang diurai akan menampilkan kolom dengan nilai 0. Agar tidak menyesatkan pengguna, jangan menampilkan jarak nol kepada pengguna.

Pengoptimalan Pelengkapan Otomatis (Baru)

Bagian ini menjelaskan praktik terbaik untuk membantu Anda memaksimalkan layanan Autocomplete (New).

Berikut ini beberapa pedoman umum:

• Cara tercepat untuk mengembangkan antarmuka pengguna yang berfungsi adalah dengan menggunakan widget Autocomplete (Baru) Maps JavaScript API, widget Autocomplete (Baru) Places SDK for Android, atau widget Autocomplete (Baru) Places SDK for iOS.
• Pahami kolom data Pelengkapan Otomatis (Baru) yang penting sejak awal.
• Kolom pembiasan lokasi dan pembatasan lokasi bersifat opsional, tetapi dapat memberikan dampak signifikan terhadap performa pelengkapan otomatis.
• Gunakan penanganan error untuk memastikan aplikasi Anda terdegrasi secara halus jika API menampilkan error.
• Pastikan aplikasi Anda menanganinya jika tidak ada pilihan dan menawarkan cara kepada pengguna untuk melanjutkan.

Praktik terbaik pengoptimalan biaya

Pengoptimalan biaya dasar

Untuk mengoptimalkan biaya penggunaan layanan Autocomplete (Baru), gunakan mask kolom di widget Place Details (Baru) dan Autocomplete (Baru) agar hanya menampilkan kolom data Autocomplete (Baru) yang Anda butuhkan.

Pengoptimalan biaya lanjutan

Pertimbangkan implementasi Autocomplete (New) yang terprogram untuk mengakses SKU: Autocomplete Request pricing dan meminta hasil Geocoding API tentang tempat yang dipilih, bukan Place Details (New). Harga per permintaan yang dipasangkan dengan Geocoding API lebih hemat biaya daripada harga per sesi (berbasis sesi) jika kondisi berikut terpenuhi:

• Jika Anda hanya memerlukan lintang dan bujur atau alamat tempat yang dipilih pengguna, Geocoding API akan mengirimkan informasi ini dengan biaya yang lebih murah daripada panggilan Place Details (Baru).
• Jika pengguna memilih prediksi pelengkapan otomatis dalam rata-rata empat permintaan prediksi Autocomplete (Baru) atau kurang, harga per permintaan dapat lebih hemat biaya daripada harga per sesi.

Apakah aplikasi Anda memerlukan informasi selain alamat dan lintang/bujur dari prediksi yang dipilih?

Praktik terbaik performa

Panduan berikut menjelaskan cara mengoptimalkan performa Autocomplete (Baru):

• Tambahkan pembatasan negara, pembiasan lokasi, dan (untuk penerapan terprogram) preferensi bahasa ke penerapan Pelengkapan Otomatis (Baru) Anda. Preferensi bahasa tidak diperlukan dengan widget karena widget tersebut memilih preferensi bahasa dari browser atau perangkat seluler pengguna.
• Jika Autocomplete (New) disertai sebuah peta, Anda dapat membiaskan lokasi berdasarkan area pandang peta.
• Jika pengguna tidak memilih salah satu prediksi Pelengkapan Otomatis (Baru), umumnya karena tidak satu pun prediksi tersebut yang merupakan alamat hasil yang diinginkan, Anda dapat menggunakan kembali input pengguna yang asli untuk mendapatkan hasil yang lebih relevan:
  • Jika Anda mengharapkan pengguna hanya memasukkan informasi alamat, gunakan kembali input pengguna yang asli dalam panggilan ke Geocoding API.
  • Jika Anda memperkirakan pengguna akan memasukkan kueri untuk tempat tertentu berdasarkan nama atau alamat, gunakan permintaan Place Details (Baru). Jika hasil hanya diharapkan di wilayah tertentu, gunakan pembiasan lokasi.
  Skenario lain saat Anda sebaiknya beralih kembali ke Geocoding API mencakup:
  • Pengguna yang memasukkan alamat sub-premis, seperti alamat untuk unit atau apartemen tertentu dalam sebuah gedung. Misalnya, alamat Ceko "Stroupežnického 3191/17, Praha" akan menghasilkan prediksi parsial di Autocomplete (Baru).
  • Pengguna memasukkan alamat dengan awalan segmen jalan seperti "23-30 29th St, Queens" di New York City atau "47-380 Kamehameha Hwy, Kaneohe" di pulau Kauai di Hawai'i.

Penyesuaian lokasi

Membiaskan hasil ke area tertentu dengan meneruskan parameter location dan parameter radius. Hal ini menginstruksikan Autocomplete (Baru) untuk memilih menampilkan hasil dalam area yang ditentukan. Hasil di luar area yang ditentukan mungkin tetap ditampilkan. Anda dapat menggunakan parameter includedRegionCodes untuk memfilter hasil agar hanya menampilkan tempat dalam negara yang ditentukan.

Membatasi lokasi

Batasi hasil ke area tertentu dengan meneruskan parameter locationRestriction.

Anda juga dapat membatasi hasil ke wilayah yang ditentukan oleh parameter location dan radius, dengan menambahkan parameter locationRestriction. Hal ini menginstruksikan Autocomplete (Baru) untuk menampilkan hanya hasil dalam wilayah tersebut.

Cobalah!

APIs Explorer memungkinkan Anda membuat contoh permintaan sehingga Anda dapat memahami API dan opsi API.

1. Pilih ikon API api di sisi kanan halaman.

2. Edit parameter permintaan jika perlu.

3. Pilih tombol Execute. Dalam dialog, pilih akun yang ingin Anda gunakan untuk membuat permintaan.

4. Di panel APIs Explorer, pilih ikon layar penuh fullscreen untuk meluaskan jendela APIs Explorer.