자동 완성 (신규) 서비스는 요청에 대한 응답으로 장소 추천을 반환하는 iOS API입니다. 요청에서 텍스트 검색 문자열과 검색 영역을 제어하는 지리적 경계를 지정합니다.
자동 완성 (신규) 서비스는 입력의 전체 단어 및 하위 문자열을 일치시켜 장소 이름, 주소, 플러스 코드를 결정할 수 있습니다. 따라서 사용자가 입력할 때 애플리케이션에서 쿼리를 전송하여 즉시 장소 추천을 제공할 수 있습니다.
장소 추천은 지정된 입력 텍스트 문자열과 검색 영역을 기반으로 한 비즈니스, 주소, 관심 장소 등의 장소입니다.
예를 들어 부분 사용자 입력 'Sicilian piz'가 포함된 문자열을 입력으로 사용하여 API를 호출하고 검색 영역은 캘리포니아주 샌프란시스코로 제한됩니다. 응답에는 장소에 대한 세부정보와 함께 'Sicilian Pizza Kitchen'이라는 이름의 식당 등 검색 문자열 및 검색 영역과 일치하는 장소 추천 목록이 포함됩니다.
반환된 장소 추천은 사용자가 원하는 장소를 선택할 수 있도록 표시되도록 설계되었습니다. 장소 세부정보(신규) 요청을 통해 반환된 장소 추천에 대한 자세한 정보를 가져올 수 있습니다.
자동 완성 (신규) 요청
GMSPlaceClient에서 메서드를 호출하여 자동 완성 요청을 만듭니다.
GMSAutocompleteRequest 객체에서 매개변수를 전달할 수 있습니다. 응답은 GMSAutocompletePlaceSuggestion 객체 내에 자동 완성 추천 용어를 제공합니다.
API 키와 query 매개변수는 필수입니다. GMSAutocompleteSessionToken를 포함하여 요청을 결제 세션과 연결하고 GMSAutocompleteFilter를 포함하여 결과에 적용할 수도 있습니다.
필수 및 선택적 매개변수에 대한 자세한 내용은 이 문서의 매개변수 섹션을 참고하세요.
Swift
let token = GMSAutocompleteSessionToken()
let northEastBounds = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWestBounds = CLLocationCoordinate2DMake(37.395804, -122.077023)
let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northEastBounds, southWestBounds)
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
// Handle response
})
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.
}
}
}];
GooglePlacesSwift
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.
}
자동 완성 (신규) 응답
자동 완성은 최대 5개의 GMSAutocompleteSuggestion 인스턴스로 구성된 배열을 반환합니다. 배열에는 다음이 포함됩니다.
placeIDtypes: 이 장소에 적용되는 유형distanceMeters: 출발지로부터의 거리attributedFullText: 사람이 읽을 수 있는 전체 추천 텍스트입니다.attributedPrimaryText: 사람이 읽을 수 있는 추천 검색어의 기본 텍스트입니다.attributedSecondaryText: 사람이 읽을 수 있는 추천의 보조 텍스트입니다.structuredFormat: 구체적인 이름과 명확한 텍스트(예: 도시 또는 지역)입니다.
필수 매개변수
query
검색할 텍스트 문자열입니다. 전체 단어 및 하위 문자열, 장소 이름, 주소, 플러스 코드를 지정합니다. Autocomplete (신규) 서비스는 이 문자열을 기준으로 일치 가능성이 있는 항목을 반환하고 감지된 관련성을 기준으로 검색 결과의 순서를 지정합니다.
선택적 매개변수
유형
장소에는 연결된 테이블 A 또는 테이블 B 유형의 단일 기본 유형만 있을 수 있습니다.
예를 들어 기본 유형은 mexican_restaurant 또는 steak_house일 수 있습니다.
기본적으로 API는 장소와 연결된 기본 유형 값과 관계없이 input 매개변수를 기반으로 모든 장소를 반환합니다. types 매개변수를 전달하여 결과를 특정 기본 유형 또는 기본 유형으로 제한합니다.
이 매개변수를 사용하여 표 A 또는 표 B에서 최대 5개의 유형 값을 지정합니다. 장소는 응답에 포함할 지정된 기본 유형 값 중 하나와 일치해야 합니다.
다음과 같은 경우 INVALID_REQUEST 오류와 함께 요청이 거부됩니다.
- 5개 이상의 유형이 지정되었습니다.
- 인식할 수 없는 유형이 모두 지정되었습니다.
국가
최대 15개의 ccTLD ('최상위 도메인') 두 문자 값의 배열로 지정된 지정된 지역 목록의 결과만 포함합니다. 생략할 경우 응답에 제한이 적용되지 않습니다. 예를 들어 리전을 독일과 프랑스로 제한하는 방법은 다음과 같습니다.
Swift
let filter = GMSAutocompleteFilter() filter.countries = ["DE", "FR"]
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.countries = @[ @"DE", @"FR" ];
GooglePlacesSwift
let filter = AutocompleteFilter(countries: ["DE", "FR"])
locationRestriction와 countries를 모두 지정하면 두 설정이 교차하는 영역에 결과가 표시됩니다.
inputOffset
input에서 커서 위치를 나타내는 0 기준 유니코드 문자 오프셋입니다. 커서 위치는 반환되는 예상 검색어에 영향을 줄 수 있습니다. 비어 있으면 기본값은 input 길이입니다.
locationBias 또는 locationRestriction
locationBias 또는 locationRestriction을 지정할 수 있지만 둘 다 지정할 수는 없습니다. locationRestriction은 결과가 포함되어야 하는 영역을 지정하는 것으로, locationBias는 결과가 근처에 있어야 하지만 영역 밖에 있을 수 있는 영역을 지정하는 것으로 생각하세요.
locationBias는 검색할 영역을 지정합니다. 이 위치는 편중으로 기능합니다. 즉, 지정된 지역 외부의 결과를 포함하여 지정된 위치 주변의 결과가 반환될 수 있습니다.locationRestriction는 검색할 영역을 지정합니다. 지정된 영역을 벗어난 결과는 반환되지 않습니다.
locationBias 또는 locationRestriction 영역을 직사각형 표시 영역 또는 원형으로 지정합니다.
원은 중심점과 반지름(미터)으로 정의됩니다. 반경은 0.0 이상, 50000.0 이하여야 합니다. 기본값은 0.0입니다. locationRestriction의 경우 반경을 0.0보다 큰 값으로 설정해야 합니다.
그렇지 않으면 요청에서 결과가 반환되지 않습니다.
예를 들면 다음과 같습니다.
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);
GooglePlacesSwift
let center = CLLocationCoordinate2DMake(40.477398, -74.259087) let bias = CircularCoordinateRegion(center: center, radius: 1000.0) let filter = AutocompleteFilter(coordinateRegionBias: bias)
직사각형은 위도-경도 표시 영역으로, 대각선 방향으로 두 개의 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를 모두 채워야 하며 표시된 상자는 비워 둘 수 없습니다. 표시 영역이 비어 있으면 오류가 발생합니다.
예를 들어 이 표시 영역은 뉴욕시를 완전히 둘러쌉니다.
Swift
let high = CLLocationCoordinate2DMake(40.477398, -74.259087) let low = CLLocationCoordinate2DMake(40.921628, -73.700051) 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);
GooglePlacesSwift
let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087) let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051) let filter = AutocompleteFilter(coordinateRegionBias: bias)
원산지
목적지까지의 직선 거리를 계산할 출발지입니다 (distanceMeters로 반환됨). 이 값을 생략하면 직선 거리는 반환되지 않습니다. 위도 및 경도 좌표로 지정해야 합니다.
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];
GooglePlacesSwift
let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))
regionCode
응답 형식을 지정하는 데 사용되는 지역 코드로, 2자리 ccTLD ('최상위 도메인') 값으로 지정됩니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하지만 일부 눈에 띄는 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk'(.co.uk)이지만 ISO 3166-1 코드는 'gb' (기술적으로 '영국 및 북아일랜드' 엔티티)입니다.
잘못된 지역 코드를 지정하면 API가 INVALID_ARGUMENT 오류를 반환합니다. 매개변수는 관련 법률에 따라 결과에 영향을 미칠 수 있습니다.
sessionToken
세션 토큰은 자동 완성 (신규) 호출을 '세션'으로 추적하는 사용자 생성 문자열입니다. Autocomplete (신규)는 세션 토큰을 사용하여 사용자 자동 완성 검색의 쿼리 및 선택 단계를 결제 목적의 개별 세션으로 그룹화합니다. 자세한 내용은 세션 토큰을 참고하세요.
자동 완성 (신규) 예시
locationRestriction 및 locationBias 사용
자동 완성 (신규)은 기본적으로 IP 상세 검색을 사용하여 검색 영역을 제어합니다. IP 상세 검색을 통해 API는 기기의 IP 주소를 사용하여 결과를 바이어스합니다. 선택적으로 locationRestriction 또는 locationBias를 사용할 수 있지만 둘 다 사용할 수는 없습니다. 이렇게 하면 검색할 영역을 지정할 수 있습니다.
위치 제한은 검색할 지역을 지정합니다. 지정된 영역 밖의 결과는 반환되지 않습니다. 다음 예에서는 위치 제한을 사용하여 샌프란시스코를 중심으로 한 5,000m 반경의 원형 위치 제한으로 요청을 제한합니다.
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:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
// Handle response
})
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.
}
}
}];
GooglePlacesSwift
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.locationBias = GMSPlaceCircularLocationOption(center, radius)
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
// Handle response
})
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.
}
}
}];
GooglePlacesSwift
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.
}
사용 유형
요청 결과를 테이블 A와 테이블 B에 나열된 특정 유형으로 제한하려면 유형 매개변수를 사용합니다. 최대 5개 값의 배열을 지정할 수 있습니다. 생략하면 모든 유형이 반환됩니다.
다음 예에서는 'Socer' 쿼리 문자열을 지정하고 types 매개변수를 사용하여 결과를 "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
// Handle response
})
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.
}
}
}];
GooglePlacesSwift
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.
}
출처 사용
위도와 경도 좌표로 지정된 origin 매개변수를 요청에 포함하면 API에 출발지에서 목적지까지 직선 거리가 응답에 포함됩니다. 응답에서 거리가 distanceMeters로 반환됩니다.
다음 예는 원점을 샌프란시스코의 중심으로 설정합니다.
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
// Handle response
})
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.
}
}
}];
GooglePlacesSwift
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.
}
기여 분석
지도 없이도 Autocomplete (신규) 기능을 사용할 수 있습니다. 지도를 표시하는 경우에는 반드시 Google 지도를 사용해야 합니다. 지도 없이 자동 완성 (신규) 서비스의 추천 검색어를 표시하는 경우 검색 필드/결과와 나란히 표시된 Google 로고를 포함해야 합니다. 자세한 내용은 Google 로고 및 저작자 표시를 참고하세요.