Autocomplete(新版)サービスは、リクエストに応じて場所の候補を返す iOS API です。リクエストでは、テキスト検索文字列に加え、検索対象地域を限定する地理的境界を指定します。
Autocomplete(新版)サービスは、入力された完全な単語や部分文字列を照合して、場所の名前や住所、Plus Codes を解決できます。これにより、アプリケーションはユーザーの入力に合わせて随時クエリを送信し、場所の候補をリアルタイムで表示することができます。
場所の候補は、指定された入力テキスト文字列と検索エリアに基づいて表示される、お店やサービス、住所、スポットなどの場所です。
たとえば、ユーザー入力の一部である「Spagh」を含む文字列を入力として使用し、検索エリアをニューヨーク市に限定して API を呼び出します。レスポンスには、検索文字列と検索エリアに一致する場所の候補のリスト(「Cafe Spaghetti」という名前のレストランなど)と、場所の詳細が含まれます。
返された場所の候補は、ユーザーが目的の場所を選択できるように、ユーザーに提示されるように設計されています。Place Details(新版)リクエストを送信すると、返された場所の候補に関する詳細情報を取得できます。
予測入力(新版)の機能をアプリに統合する方法は、主に 2 つあります。
- プログラムで場所の予測を取得する: API を直接呼び出して予測を取得し、カスタム ユーザー インターフェースに表示します。
- Place Autocomplete ウィジェットを追加する: ユーザーが入力すると予測候補が表示される、すぐに使用できる検索予測入力機能を提供します。
プログラムで場所の予測を取得する
Autocomplete(新版)リクエスト
GMSPlacesClient のメソッドを呼び出して、予測入力リクエストを作成します。パラメータは GMSAutocompleteRequest オブジェクトで渡すことができます。レスポンスでは、GMSAutocompletePlaceSuggestion オブジェクト内に予測入力の候補が返されます。
API キーと query パラメータは必須です。GMSAutocompleteSessionToken を含めてリクエストを課金セッションに関連付け、GMSAutocompleteFilter を結果に適用することもできます。
Places Swift SDK のバージョン
PlacesClient のメソッドを呼び出して、予測入力リクエストを作成します。パラメータは AutocompleteRequest オブジェクトで渡すことができます。レスポンスでは、AutocompletePlaceSuggestion オブジェクト内に予測入力の候補が返されます。
API キーと query パラメータは必須です。AutocompleteSessionToken を含めてリクエストを請求セッションに関連付け、AutocompleteFilter を結果に適用することもできます。
必須パラメータとオプション パラメータの詳細については、このドキュメントのパラメータ セクションをご覧ください。
Places Swift SDK
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. }
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. } } }];
Autocomplete(新版)のレスポンス
予測入力は、最大 5 つの GMSAutocompleteSuggestion インスタンスの配列を返します。配列には次のものが含まれます。
placeIDtypes: この場所に適用されるタイプ。distanceMeters: 起点からの距離。attributedFullText: : 候補の完全なテキスト(人が読める形式)。attributedPrimaryText: 候補の人が読める形式のメインテキスト。attributedSecondaryText: 候補の人が読める形式のセカンダリ テキスト。structuredFormat: 特定の名前と曖昧性除去テキスト(都市や地域など)。
必須パラメータ
クエリ
検索するテキスト文字列。完全な単語や部分文字列、場所の名前、住所、Plus Codes を指定します。Autocomplete(新版)サービスは、この文字列と一致する候補を、関連性の高い順に並べて結果として返します。
オプション パラメータ
sessionToken
セッション トークンは、Autocomplete(新版)の呼び出し(ウィジェット経由の呼び出しとプログラムによる呼び出しの両方)を「セッション」として追跡する、ユーザーが生成した文字列です。Autocomplete(新版)はセッション トークンを使用し、請求処理のために予測入力検索でのユーザーのクエリと選択フェーズを個別のセッションにグループ化します。
Places Autocomplete セッション トークンを公開して、Places SDK for iOS の一部ではない他のサービス(Address Validation など)に渡すことができます。
Places Swift SDK
let token = AutocompleteSessionToken() let filter = AutocompleteFilter(origin: CLLocationCoordinate2DMake(39.7, -94.5)) let request = AutocompleteRequest(query: "Piz", sessionToken: token, filter: filter) PlacesClient.shared.fetchAutocompleteSuggestions(request: request) { case .success(let suggestions): ... case .failure(let placesError): print(placesError) } // pass token's string format to use with a service that is not a part of iOS SDK. print("token: \(token)")
Objective-C
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Piz"]; GMSAutocompleteSessionToken *token = [[GMSAutocompleteSessionToken alloc] init]; request.sessionToken = token; GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.origin = [[CLLocation alloc] initWithLatitude:39.7 longitude:-94.5]; filter.locationBias = GMSPlaceRectangularLocationOption(topLocation, bottomLocation); request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> *_Nullable results, NSError *_Nullable error) { ... }]; // pass token's string format to use with a service that is not a part of iOS SDK. NSLog(@"%@", token.description);
詳細については、セッション トークンをご覧ください。
省略可能な AutocompleteFilter パラメータ
タイプ
1 つの場所に関連付けることができるメインタイプは、表 A または表 B のタイプのうち 1 つのみです。たとえば、プライマリ タイプは mexican_restaurant や steak_house になります。
デフォルトでは、API は、場所に関連付けられたプライマリ タイプの値に関係なく、input パラメータに基づいてすべての場所を返します。types パラメータを渡して、結果を特定のプライマリ タイプに制限します。
このパラメータを使用して、表 A または表 B から最大 5 つのタイプ値を指定します。レスポンスに含めるには、指定されたプライマリ タイプ値のいずれかに一致する必要があります。
次の場合、リクエストは INVALID_REQUEST エラーで拒否されます。
- 指定したタイプの数が 5 個より多い。
- 認識できないタイプが指定されている。
たとえば、結果をスポーツ用品店に限定するには、AutocompleteFilter でそのタイプを指定します。
Places Swift SDK
let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
Swift
let filter = GMSAutocompleteFilter() filter.types = ["sporting_goods_store"]
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.types = @[ "sporting_goods_store" ];
実施国数
指定されたリージョンのリストの結果のみを含めます。最大 15 個の ccTLD(「トップレベル ドメイン」)の 2 文字の値の配列として指定します。省略すると、レスポンスに制限は適用されません。たとえば、地域をドイツとフランスに制限するには、次のようにします。
Places Swift SDK
let filter = AutocompleteFilter(countries: ["DE", "FR"])
Swift
let filter = GMSAutocompleteFilter() filter.countries = ["DE", "FR"]
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.countries = @[ @"DE", @"FR" ];
locationRestriction と countries の両方を指定すると、2 つの設定の交差する領域に結果が配置されます。
inputOffset
input のカーソル位置を示すゼロベースの Unicode 文字オフセット。カーソルの位置は、返される予測に影響する可能性があります。空の場合、デフォルトは input の長さになります。
locationBias または locationRestriction
locationBias または locationRestriction を指定して検索エリアを定義できますが、両方を指定することはできません。locationRestriction は、結果がその範囲内になければならないリージョンを指定するものと考え、locationBias は、結果がそのエリアの近くになければならないが、エリア外でもよいリージョンを指定するものと考えてください。
locationBiasは、検索するエリアを指定します。この場所はバイアスとして機能します。つまり、指定された場所の周辺の結果(指定されたエリア外の結果を含む)が返される可能性があります。locationRestrictionは、検索するエリアを指定します。指定した範囲外の結果は返されません。
locationBias または locationRestriction のリージョンを、長方形のビューポートまたは円として指定します。
円は、中心点と半径(メートル単位)で定義されます。半径は 0.0 ~ 50000.0(指定した値を含む)の範囲で指定してください。デフォルト値は 0.0 です。locationRestriction の場合、半径を 0.0 より大きい値に設定する必要があります。それ以外の場合、リクエストは結果を返しません。
次に例を示します。
Places Swift SDK
let center = CLLocationCoordinate2DMake(40.477398, -74.259087) let bias = CircularCoordinateRegion(center: center, radius: 1000.0) let filter = AutocompleteFilter(coordinateRegionBias: bias)
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);
長方形は、対角線上にある 2 つの low 点と high 点で表される緯度経度のビューポートです。ビューポートは閉じた領域と見なされます。つまり、境界が含まれます。緯度の範囲は -90 ~ 90 度、経度の範囲は -180 ~ 180 度にする必要があります。
low=highの場合、ビューポートはその単一のポイントで構成されます。low.longitude>high.longitudeの場合、経度の範囲は反転します(ビューポートは経度 180 度の線をまたぎます)。low.longitude= -180 度、high.longitude= 180 度の場合、ビューポートにはすべての経度が含まれます。low.longitude= 180 度、high.longitude= -180 度の場合、経度範囲は空になります。
low と high の両方を入力する必要があります。また、表されるボックスを空にすることはできません。ビューポートが空の場合、エラーが発生します。
たとえば、次のビューポートはニューヨーク市を完全に囲んでいます。
Places Swift SDK
let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087) let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051) let filter = AutocompleteFilter(coordinateRegionBias: bias)
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);
origin
目的地までの直線距離を計算する起点(distanceMeters として返されます)。この値を省略すると、直線距離は返されません。緯度と経度の座標として指定する必要があります。
Places Swift SDK
let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))
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];
regionCode
レスポンスのフォーマットに使用される地域コード。ccTLD(「トップレベル ドメイン」)の 2 文字の値として指定します。大半の ccTLD コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」(.co.uk)ですが、ISO 3166-1 コードは「gb」です(厳密には「グレート ブリテンおよび北アイルランド連合王国」のエンティティ)。
無効なリージョン コードを指定すると、API から INVALID_ARGUMENT エラーが返されます。このパラメータは、適用される法律に基づいて結果に影響する可能性があります。
shouldIncludePureServiceAreaBusinesses
true の場合、レスポンス配列に非店舗型ビジネスのみを返します。純粋な非店舗型ビジネスとは、客先に出向いてサービスや商品を提供し、ビジネス拠点の住所では接客しないビジネスです。
次に例を示します。
Places Swift SDK
let filter = AutocompleteFilter() filter.shouldIncludePureServiceAreaBusinesses = true
Swift
let filter = AutocompleteFilter() filter.shouldIncludePureServiceAreaBusinesses = true
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.shouldIncludePureServiceAreaBusinesses = YES;
Place Autocomplete ウィジェットを追加する
一貫した Place Autocomplete エクスペリエンスをより簡単に提供するには、Place Autocomplete ウィジェットをアプリに追加します。このウィジェットは、ユーザー入力を処理して場所の予測をユーザーに表示する専用の全画面インターフェースを提供し、AutocompletePlaceSuggestion オブジェクトをアプリに返します。その後、Place Details(新版)リクエストを送信して、場所の予測に関する追加情報を取得できます。
プログラムによって場所の候補を取得する場合と同様に、Place Autocomplete ウィジェットでは、セッション トークンを使用して、予測入力リクエストをセッションにグループ化して課金できます。セッション トークンを渡すには、AutocompleteSessionToken() を呼び出します。
セッション トークンを指定しない場合、ウィジェットは予測入力セッション トークンを作成します。このトークンは onSelection コールバックから取得できます。セッション トークンの使用方法については、セッション トークンについてをご覧ください。
show バインディング値が true に設定されている場合、ユーザーは場所を選択できる全画面表示に移動します。ユーザーが入力すると、ウィジェットは店舗、住所、スポットなどの場所の候補を返します。ユーザーが場所を選択すると、ウィジェットは選択された場所を指定して onSelection ハンドラを呼び出し、全画面表示を閉じます。
Place Autocomplete ウィジェットのパラメータ
Place Autocomplete ウィジェットには、プログラムで使用できるパラメータに加えて、次のパラメータも用意されています。
表示する
show は、ウィジェットを表示するかどうかを指定します。
onSelection
場所が選択されたときに実行されるクロージャ。
onError
エラーが発生したときに実行するクロージャ。エラーが発生した場合は、PlacesError が渡されます。
コンテンツとテーマのカスタマイズ
AutocompleteUICustomization パラメータは、ウィジェットに適用する UI カスタマイズを指定します。カスタマイズ オプションは次のとおりです。
AutocompleteListDensity。このパラメータを使用すると、候補リストの密度をmultiLineまたはtwoLineのいずれかから選択できます。AutocompleteUIIcon。このパラメータでは、各リストアイテムのデフォルト アイコンを表示するかどうかを選択できます。theme。このパラメータは、デフォルトのスタイル属性をオーバーライドするカスタムテーマを指定します。Place Autocomplete コンポーネントの色、タイポグラフィ、間隔、枠線、角をカスタマイズできます。デフォルトはPlacesMaterialThemeです。オーバーライドされていないテーマ属性は、デフォルトのスタイルを使用します。
完全なコード例をご覧ください。
Autocomplete(新版)の例
locationRestriction と locationBias を使用する
Autocomplete(新版)では、デフォルトで IP バイアスを使用して検索エリアを制御します。IP バイアスを使用すると、API はデバイスの IP アドレスを使用して結果をバイアスします。必要に応じて、locationRestriction または locationBias を使用して検索するエリアを指定できます。ただし、両方を指定することはできません。
地域の制限では、検索対象の地域を指定します。指定した範囲外の結果は返されません。次の例では、位置情報の制限を使用して、サンフランシスコを中心とする半径 5,000 メートルの円形の位置情報の制限にリクエストを制限しています。
Places Swift SDK
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. }
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
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. }
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. } } }];
用途
types パラメータを使用すると、リクエストの結果を、表 A と表 B に記載されている特定のタイプに制限できます。最大 5 つの値の配列を指定できます。省略すると、すべてのタイプが返されます。
次の例では、クエリ文字列「Soccer」を指定し、types パラメータを使用して、結果を "sporting_goods_store" タイプの施設に制限しています。
Places Swift SDK
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. }
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. } } }];
オリジンを使用
リクエストに origin パラメータを緯度と経度の座標として指定すると、API は出発地から目的地までの直線距離をレスポンスに含めます。レスポンスは、距離を distanceMeters として返します。
この例では、起点をサンフランシスコの中心に設定しています。
Places Swift SDK
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. }
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. } } }];
コンテンツとテーマをカスタマイズする
Swift
let uiCustomization = AutocompleteUICustomization( listDensity: .multiLine, listItemIcon: .noIcon, theme: PlacesMaterialTheme() )
Place Autocomplete ウィジェットを追加する(完全なコード)
Places Swift SDK
struct PlaceAutocompleteDemoView: View { @State private var fetchedPlace: Place? @State private var placesError: PlacesError? @State private var showWidget = false public var body: some View { VStack { Button("Search for a place") { showWidget.toggle() } .placeAutocomplete( show: $showWidget, onSelection: { (autocompletePlaceSuggestion, autocompleteSessionToken) in Task { let placesClient = await PlacesClient.shared let fetchPlaceRequest = FetchPlaceRequest( placeID: autocompletePlaceSuggestion.placeID, placeProperties: [.displayName, .formattedAddress], sessionToken: autocompleteSessionToken ) switch await placesClient.fetchPlace(with: fetchPlaceRequest) { case .success(let place): print("Fetched place: \(place)") self.fetchedPlace = place case .failure(let placesError): print("Failed to fetch place: \(placesError)") self.placesError = placesError } } }, onError: { placesError in self.placesError = placesError } ) } } }
Autocomplete(新版)の最適化
このセクションでは、Autocomplete(新版)サービスを最大限に活用するためのヒントを紹介します。
概要は次のとおりです。
- 機能的なユーザー インターフェースを最も手早く作成するには、Maps JavaScript API Autocomplete(新版)ウィジェット、Places SDK for Android Autocomplete(新版)ウィジェット、または Places SDK for iOS Autocomplete(新版)ウィジェットを使用します。
- Autocomplete(新版)のデータ フィールドの基本を理解します。
- 位置情報のバイアスと位置情報の制限のフィールドは省略可能ですが、予測入力のパフォーマンスに大きく影響する場合があります。
- エラー処理を使用して、API がエラーを返した場合に、アプリでグレースフル デグラデーションが行われるようにします。
- アプリでは、選択肢がない場合でもユーザーが操作を続行できるようにします。
費用の最適化に関するヒント
基本的な費用の最適化
Autocomplete(新版)サービスの費用を最適化するには、Place Details(新版)と Autocomplete(新版)ウィジェットのフィールド マスクを使用して、必要な Autocomplete(新版)のデータ フィールドのみを返すよう設定します。
高度な費用の最適化
SKU: Autocomplete Request の料金設定を利用し、Place Details(新版)の代わりに選択された場所に関する Geocoding API の結果をリクエストするためには、Autocomplete(新版)のプログラマティック実装を行うことをおすすめします。次の両方に該当する場合は、リクエストあたりの料金設定と Geocoding API を組み合わせた方が、セッションあたり(セッション ベース)の料金設定よりも費用対効果が高くなります。
- ユーザーが選択した場所の緯度と経度または住所のみが必要な場合。その場合は、Geocoding API の方が、Place Details(新版)の呼び出しよりも少ないコストでこの情報を提供できます。
- ユーザーが予測結果を選択するまでの予測入力候補(新版)リクエストの回数が、平均 4 回以下の場合。その場合は、リクエストあたりの料金設定の方がセッションあたりの料金設定よりも費用対効果が高くなります。
| アプリケーションに必要なもの | ユーザーが予測を選択するまでの Autocomplete(新版)リクエストの平均数 | おすすめの実装方法 |
|---|---|---|
| 住所と位置以外の Place Details(場所の名前、ビジネスのステータス、営業時間など) | その他の数字 | セッション ベースの Autocomplete(新版)と Place Details(新版) |
| 選択された予測結果の住所と緯度 / 経度のみ | 4 以下 | リクエストごとの Autocomplete(新版)と Geocoding API |
| 選択された予測結果の住所と緯度 / 経度のみ | 4 回以上 | 住所のみのアプリケーション向けのセッション ベースの Autocomplete(新版) |
Autocomplete(新版)使用時のパフォーマンスによっては、アプリケーションで Places Details(新版)を使用するよりも、Geocoding API を使用した方が費用対効果が高くなる場合があります。アプリケーションの予測入力(新版)の効率は、ユーザーの入力内容や、アプリケーションが使用される場所、パフォーマンス最適化のベスト プラクティスが導入されているかどうかによって変わります。
表のリクエストの平均数を確認するには、ユーザーがアプリケーション内で Autocomplete(新版)の予測を選択するまでに、平均でどのくらいの文字数を入力するのかを分析します。
セッション ベースの Autocomplete(新版)と Place Details(新版)
セッション ベースの Autocomplete(新版)と Place Details(新版)を併用します。
アプリケーションで Place Details(新版)(場所の名前、営業状況、営業時間など)が必要な場合、Autocomplete(新版)の実装では、セッション トークン(プログラムで、または JavaScript、Android、iOS ウィジェットに組み込まれている)をセッションごとに使用し、リクエストする場所データ フィールドに応じて、該当する Places SKU を使用する必要があります。1
ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Autocomplete(新版)リクエストと Place Details(新版)リクエストの両方が含まれます。必要な Autocomplete(新版)のデータ フィールドのみをリクエストするように、必ず fields パラメータを指定してください。
プログラマティック実装
Autocomplete(新版)リクエストでセッション トークンを使用します。選択された予測結果に関する Place Details(新版)をリクエストする際は、次のパラメータを含めます。
- Autocomplete(新版)レスポンスのプレイス ID
- Autocomplete(新版)リクエストで使用されるセッション トークン
- 必要な Autocomplete(新版)のデータ フィールドを指定する
fieldsパラメータ
Geocoding API を使用したリクエストごとの Autocomplete(新版)
セッション トークンを使用せずにプログラムによって Autocomplete(新版)を実装し、選択された場所の予測で Geocoding API を呼び出します。
Geocoding API は、住所と緯度 / 経度の座標を提供します。
Autocomplete Requests のリクエスト 4 件と、選択された場所予測に関する Geocoding API の呼び出しを合わせた料金は、Autocomplete(新規)のセッション 1 回あたりの料金よりも少ないコストです。1
パフォーマンスに関するベスト プラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める候補を提供できるようすることをおすすめします。
住所のみのアプリケーション向けのセッション ベースの Autocomplete(新版)
セッション ベースの Autocomplete(新版)と Place Details(新版)を併用します。
ユーザーが Autocomplete(新版)の予測を選択するまでに予想されるリクエストの平均数が、セッションあたりの料金を上回るため、Autocomplete(新版)の実装では、Autocomplete(新版)リクエストと関連する Place Details(新版)リクエストの両方にセッション トークンを使用する必要があります。
セッションごと。
1
ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Autocomplete(新版)リクエストと Place Details(新版)リクエストの両方が含まれます。必要なフィールドのみをリクエストするように、必ず fields パラメータを指定してください。
プログラマティック実装
Autocomplete(新版)リクエストでセッション トークンを使用します。選択された予測結果に関する Place Details(新版)をリクエストする際は、次のパラメータを含めます。
- Autocomplete(新版)レスポンスのプレイス ID
- Autocomplete(新版)リクエストで使用されるセッション トークン
- 住所やジオメトリなどのフィールドを指定する
fieldsパラメータ
Autocomplete(新版)リクエストを遅らせることを検討する
ユーザーが最初の 3 ~ 4 文字を入力するまで Autocomplete(新版)リクエストを遅らせて、アプリケーションでのリクエスト数を減らすこともできます。たとえば、ユーザーが 3 文字目を入力した後に、各文字に対して Autocomplete(新版)リクエストを行う場合、ユーザーが 7 文字を入力してから予測を選択し、Geocoding API リクエストを 1 回行うと、合計料金は Autocomplete(新版)Per Request 4 回分 + Geocoding の料金になります。1
リクエストを遅らせることで、プログラマティック リクエストの回数を平均 4 回以下に抑えられる場合は、高パフォーマンスで Autocomplete(新版)と Geocoding API を併用する実装に関するガイダンスをご覧ください。なお、リクエストを遅らせると、1 文字入力するたびに予測が表示されはずと考えているユーザーには、遅延と受けとられる場合もあります。
パフォーマンスに関するベスト プラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める候補を提供できるようすることをおすすめします。
-
費用については、Google Maps Platform の料金表をご覧ください。
パフォーマンスに関するベスト プラクティス
Autocomplete(新版)のパフォーマンスを最適化するためのガイドラインは次のとおりです。
- Autocomplete(新版)実装に、国別のポリシー、場所のバイアス、言語設定(プログラマティック実装の場合)を追加します。ウィジェットはユーザーのブラウザやモバイル デバイスから言語設定を選択するため、ウィジェットでは言語設定は不要です。
- Autocomplete(新版)が地図に関連付けられている場合は、地図のビューポートを基準に場所にバイアスをかけることができます。
- ユーザーがいずれかの予測入力(新版)候補を選択しなかった場合は(通常は目的の住所が候補に挙がらなかったことが原因)、ユーザーの元の入力内容を再利用して、より関連性の高い結果を取得できます。
- ユーザーが住所情報のみを入力することが予想される場合は、Geocoding API の呼び出しで、ユーザーの元の入力内容を再利用します。
- ユーザーが特定の場所に関する検索語句(名前や住所)を入力することが予想される場合は、Place Details(新版)リクエストを使用します。特定の地域の結果のみが求められる場合は、場所のバイアスを使用します。
- ユーザーが、建物内の特定のユニットやアパートの住所など、サブプレミスの住所を入力している。たとえば、チェコ語の住所「Stroupežnického 3191/17, Praha」では、Autocomplete(新版)で部分的な予測が生成されます。
- ユーザーがニューヨークの「23-30 29th St, Queens」や、ハワイのカウアイ島の「47-380 Kamehameha Hwy, Kaneohe」など、道路区間のプレフィックスを入力する場合。
位置情報のバイアス
location パラメータと radius パラメータを渡すことで、バイアスを設定し、指定した範囲内の結果を優先します。これにより、Autocomplete(新版)は、定義されたエリア内の結果を優先的に表示します。指定した範囲外の結果が返されることもあります。includedRegionCodes パラメータを使用すると、指定した国内の場所のみを表示するように結果をフィルタできます。
ロケーションの制限
locationRestriction パラメータを渡して、結果を特定のエリアに制限します。
locationRestriction パラメータを追加することで、location パラメータと radius パラメータで定義された地域に結果を制限することもできます。これにより、Autocomplete(新版)は、そのリージョン内の結果のみを返すようになります。