Place Autocomplete (Baru)

Pilih platform: Android iOS JavaScript Layanan Web

Layanan Autocomplete (Baru) adalah API iOS yang menampilkan saran tempat sebagai respons terhadap permintaan. Dalam permintaan, tentukan string penelusuran teks dan batas geografis yang mengontrol area penelusuran.

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

Saran tempat adalah tempat, seperti bisnis, alamat, dan lokasi menarik, berdasarkan string teks input dan area penelusuran yang ditentukan.

Misalnya, Anda memanggil API menggunakan string sebagai input yang berisi input pengguna sebagian, "Spagh", dengan area penelusuran terbatas pada New York City. Respons kemudian berisi daftar saran tempat yang cocok dengan string penelusuran dan area penelusuran, seperti restoran bernama "Cafe Spaghetti", beserta detail tentang tempat tersebut.

Saran tempat yang ditampilkan didesain untuk ditampilkan kepada pengguna agar mereka dapat memilih tempat yang diinginkan. Anda dapat membuat permintaan Place Details (New) untuk mendapatkan informasi selengkapnya tentang saran tempat yang ditampilkan.

Permintaan Pelengkapan Otomatis (Baru)

Buat permintaan pelengkapan otomatis dengan memanggil metode di GMSPlaceClient. Anda dapat meneruskan parameter dalam objek GMSAutocompleteRequest. Respons memberikan saran Autocomplete dalam objek GMSAutocompletePlaceSuggestion.

Kunci API dan parameter query wajib ada. Anda juga dapat menyertakan GMSAutocompleteSessionToken untuk mengaitkan permintaan dengan sesi penagihan dan GMSAutocompleteFilter untuk diterapkan ke hasil.

Untuk mengetahui informasi selengkapnya tentang parameter wajib dan opsional, lihat bagian parameter dalam dokumen ini.

Swift

let token = GMSAutocompleteSessionToken()

let northWestBounds = CLLocationCoordinate2DMake(40.921628, -73.700051)
let southEastBounds = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northWestBounds, southEastBounds)
    
let request = GMSAutocompleteRequest(query:"Spagh")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

Objective-C

CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(37.388162, -122.088137);
CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(37.395804, -122.077023);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ kGMSPlaceTypeRestaurant ];
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

Places Swift SDK for iOS (Pratinjau)

let center = (37.3913916, -122.0879074)
let northEast = (37.388162, -122.088137)
let southWest = (37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  // Handle suggestions.
case .failure(let placesError):
  // Handle error.
}

Respons Pelengkapan Otomatis (Baru)

Pelengkapan otomatis menampilkan array yang dapat berisi hingga lima instance GMSAutocompleteSuggestion. Array berisi:

  • placeID
  • types: Jenis yang berlaku untuk tempat ini.
  • distanceMeters: Jarak dari asal.
  • attributedFullText: Teks lengkap saran yang dapat dibaca manusia.
  • attributedPrimaryText: Teks utama saran yang dapat dibaca manusia.
  • attributedSecondaryText: Teks sekunder saran yang dapat dibaca manusia.
  • structuredFormat: Nama spesifik dan teks yang membedakan, seperti kota atau wilayah.

Parameter wajib

kueri

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

Parameter opsional

tipe

Tempat hanya dapat memiliki satu jenis utama dari jenis Tabel A atau Tabel B yang terkait dengannya. Misalnya, jenis utama mungkin 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 menjadi jenis utama atau jenis utama tertentu dengan meneruskan parameter types.

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 untuk disertakan dalam respons.

Permintaan ditolak dengan error INVALID_REQUEST jika:

  • Lebih dari lima jenis ditentukan.
  • Semua jenis yang tidak dikenal ditentukan.

negara

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

Swift

let filter = GMSAutocompleteFilter()
filter.countries = ["DE", "FR"]

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.countries = @[ @"DE", @"FR" ];

Places Swift SDK for iOS (Pratinjau)

let filter = AutocompleteFilter(countries: ["DE", "FR"])

Jika Anda menentukan locationRestriction dan countries, hasilnya berada di area persimpangan kedua setelan tersebut.

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.

locationBias atau locationRestriction

Anda dapat menentukan locationBias atau locationRestriction, tetapi tidak keduanya, untuk menentukan area penelusuran. Anggap locationRestriction sebagai menentukan wilayah yang harus menjadi lokasi hasil, dan locationBias sebagai menentukan wilayah yang harus menjadi lokasi hasil, 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 region 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 50.000,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:

Swift

let center = CLLocationCoordinate2DMake(40.730610, -73.935242)
let radius = 1000.0

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

Objective-C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242);
radius = 1000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);

Places Swift SDK for iOS (Pratinjau)

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

let bias = CircularCoordinateRegion(center: center, radius: 1000.0)

let filter = AutocompleteFilter(coordinateRegionBias: bias)

Persegi panjang adalah area pandang lintang-bujur, yang direpresentasikan sebagai dua titik low dan high yang saling berhadapan secara diagonal. Area pandang dianggap sebagai wilayah tertutup, yang berarti 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 terbalik (area pandang melintasi garis bujur 180 derajat).
  • Jika low.longitude = -180 derajat dan high.longitude= 180 derajat, area pandang akan menyertakan semua bujur.
  • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur akan kosong.

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

Misalnya, area pandang ini sepenuhnya mencakup New York City:

Swift

let high = CLLocationCoordinate2DMake(40.921628, -73.700051)
let low = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceRectangularLocationOption(high, low)

Objective-C

CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087);
CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(high, low);

Places Swift SDK for iOS (Pratinjau)

let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087)
let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = AutocompleteFilter(coordinateRegionBias: bias)

asal

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

Swift

let filter = GMSAutocompleteFilter()
filter.origin =  CLLocation(latitude: 37.395804, longitude: -122.077023)

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];

filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude: -122.077023];

Places Swift SDK for iOS (Pratinjau)

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))

regionCode

Kode wilayah yang digunakan untuk memformat respons, yang ditentukan sebagai nilai dua karakter ccTLD ("domain level teratas"). Umumnya 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").

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

sessionToken

Token sesi adalah string buatan pengguna yang melacak panggilan Autocomplete (Baru) sebagai "sesi". Pelengkapan Otomatis (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.

Contoh Pelengkapan Otomatis (Baru)

Menggunakan locationRestriction dan locationBias

Autocomplete (Baru) menggunakan bias IP secara default untuk mengontrol area penelusuran. Dengan bias IP, API menggunakan alamat IP perangkat untuk membiaskan hasil. Anda dapat menggunakan locationRestriction atau locationBias secara opsional, tetapi tidak keduanya, untuk menentukan area yang akan ditelusuri.

Pembatasan lokasi menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak akan ditampilkan. Contoh berikut menggunakan batasan lokasi untuk membatasi permintaan ke batasan lokasi melingkar dengan radius 5.000 meter yang berpusat di San Francisco:

Swift

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius)
    
let request = GMSAutocompleteRequest(query:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

Objective-C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

Places Swift SDK for iOS (Pratinjau)

let center = (37.775061, -122.419400)
let radius = 5000.0
let restriction = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionRestriction: restriction)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}

Dengan bias lokasi, lokasi berfungsi sebagai bias, yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan. Contoh berikutnya mengubah permintaan sebelumnya untuk menggunakan bias lokasi:

Swift

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceCircularLocationOption(center, radius)
    
let request = GMSAutocompleteRequest(query:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

Objective-C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

Places Swift SDK for iOS (Pratinjau)

let center = (37.775061, -122.419400)
let radius = 5000.0
let bias = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionBias: bias)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}

Jenis penggunaan

Gunakan parameter jenis untuk membatasi hasil dari permintaan agar memiliki jenis tertentu seperti yang tercantum dalam Tabel A dan Tabel B. Anda dapat menentukan array hingga lima nilai. Jika dihilangkan, semua jenis akan ditampilkan.

Contoh berikut menentukan string kueri "Sepak Bola" dan menggunakan parameter jenis untuk membatasi hasil ke tempat usaha dengan jenis "sporting_goods_store":

Swift

let token = GMSAutocompleteSessionToken()

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
    
let request = GMSAutocompleteRequest(query:"Soccer")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Soccer"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

Places Swift SDK for iOS (Pratinjau)

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Soccer", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}

Menggunakan origin

Saat Anda menyertakan parameter origin dalam permintaan, yang ditentukan sebagai koordinat lintang dan bujur, API akan menyertakan jarak garis lurus dari asal ke tujuan dalam respons. Respons akan menampilkan jarak sebagai distanceMeters.

Contoh ini menetapkan asal ke pusat San Francisco:

Swift

let token = GMSAutocompleteSessionToken()

let origin = CLLocation(latitude: 37.7749, longitude: -122.4194)

let filter = GMSAutocompleteFilter()

filter.origin =  origin
    
let request = GMSAutocompleteRequest(query:"Amoeba")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText)) and distance: \(String(describing: result.placeSuggestion?.distanceMeters))")
        }
      }
    })

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Amoeba"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
      }
    }
}];

Places Swift SDK for iOS (Pratinjau)

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.7749, longitude: -122.4194))
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Amoeba", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}

Atribusi

Anda dapat menggunakan Autocomplete (Baru) meskipun tanpa peta. Jika Anda menampilkan peta, maka harus peta Google. Saat menampilkan sugesti dari layanan Autocomplete (Baru) tanpa peta, Anda harus menyertakan logo Google yang ditampilkan secara inline dengan kolom/hasil penelusuran. Untuk mengetahui informasi selengkapnya, lihat Menampilkan logo dan atribusi Google.