Place Autocomplete (신규)

플랫폼 선택: Android iOS JavaScript 웹 서비스

Autocomplete (신규) 서비스는 요청에 대한 응답으로 장소 추천을 반환하는 iOS API입니다. 요청에서 검색 지역을 제어하는 텍스트 검색 문자열과 지리적 경계를 지정합니다.

자동 완성 (신규) 서비스는 입력의 전체 단어 및 하위 문자열을 일치시켜 장소 이름, 주소, Plus Code를 결정할 수 있습니다. 따라서 애플리케이션은 사용자가 입력할 때 쿼리를 전송하여 즉시 장소 추천을 제공할 수 있습니다.

장소 추천은 지정된 입력 텍스트 문자열 및 검색 지역을 기반으로 비즈니스, 주소, 관심 장소와 같은 장소입니다.

예를 들어 검색 지역을 뉴욕시로 제한하고 부분 사용자 입력인 'Spagh'가 포함된 문자열을 입력으로 사용하여 API를 호출합니다. 그러면 응답에는 검색 문자열 및 검색 지역에 일치하는 장소 추천 목록(예: 'Cafe Spaghetti'라는 식당)과 장소에 관한 세부정보가 포함됩니다.

반환된 장소 추천은 사용자가 원하는 장소를 선택할 수 있도록 사용자에게 표시되도록 설계되었습니다. 장소 세부정보(신규) 요청을 실행하여 반환된 장소 추천에 관한 자세한 정보를 확인할 수 있습니다.

자동 완성 (신규) 요청

GMSPlaceClient에서 메서드를 호출하여 자동 완성 요청을 만듭니다. GMSAutocompleteRequest 객체에서 매개변수를 전달할 수 있습니다. 응답은 GMSAutocompletePlaceSuggestion 객체 내에 자동 완성 추천 용어를 제공합니다.

API 키와 query 매개변수는 필수 항목입니다. GMSAutocompleteSessionToken를 포함하여 요청을 결제 세션과 연결하고 GMSAutocompleteFilter를 포함하여 결과에 적용할 수도 있습니다.

필수 및 선택적 매개변수에 관한 자세한 내용은 이 문서의 매개변수 섹션을 참고하세요.

SwiftObjective-CiOS용 Places Swift SDK (미리보기)
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))")
        }
      }
    })
 
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.
    }
  }
}];
 
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 인스턴스 배열을 반환합니다. 배열에는 다음이 포함됩니다.

  • placeID
  • types: 이 장소에 적용되는 유형입니다.
  • distanceMeters: 원점과의 거리입니다.
  • attributedFullText: 사람이 읽을 수 있는 전체 추천 텍스트입니다.
  • attributedPrimaryText: 사람이 읽을 수 있는 추천의 기본 텍스트입니다.
  • attributedSecondaryText: 추천의 보조 텍스트로 사람이 읽을 수 있습니다.
  • structuredFormat: 특정 이름 및 구체화 텍스트(예: 도시 또는 지역)입니다.

필수 매개변수

query

검색할 텍스트 문자열입니다. 전체 단어 및 하위 문자열, 장소 이름, 주소, Plus Code를 지정합니다. 자동 완성 (신규) 서비스는 이 문자열을 기반으로 일치 가능성이 있는 항목을 반환하고 감지된 관련성을 기반으로 검색 결과를 정렬합니다.

선택적 매개변수

유형

장소에는 연결된 표 A 또는 표 B 유형 중 단일 기본 유형만 있을 수 있습니다. 예를 들어 기본 유형은 mexican_restaurant 또는 steak_house일 수 있습니다.

기본적으로 API는 장소와 연결된 기본 유형 값과 관계없이 input 매개변수를 기반으로 모든 장소를 반환합니다. types 매개변수를 전달하여 특정 기본 유형 또는 기본 유형으로 결과를 제한합니다.

이 매개변수를 사용하여 표 A 또는 표 B에서 최대 5개의 유형 값을 지정합니다. 장소가 응답에 포함되려면 지정된 기본 유형 값 중 하나와 일치해야 합니다.

다음과 같은 경우 요청이 INVALID_REQUEST 오류로 거부됩니다.

  • 5개가 넘는 유형이 지정되었습니다.
  • 인식할 수 없는 유형이 지정됩니다.

국가

최대 15개의 ccTLD ('최상위 도메인') 2자리 값 배열로 지정된 지정된 지역 목록의 결과만 포함합니다. 생략하면 응답에 제한이 적용되지 않습니다. 예를 들어 지역을 독일과 프랑스로 제한하려면 다음을 실행합니다.

SwiftObjective-CiOS용 Places Swift SDK (미리보기)
let filter = GMSAutocompleteFilter()
filter.countries = ["DE", "FR"]
 
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.countries = @[ @"DE", @"FR" ];
 
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보다 큰 값으로 설정해야 합니다. 그렇지 않으면 요청에 결과가 반환되지 않습니다.

예를 들면 다음과 같습니다.

SwiftObjective-CiOS용 Places Swift SDK (미리보기)
let center = CLLocationCoordinate2DMake(40.730610, -73.935242)
let radius = 1000.0

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)
 
CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242);
radius = 1000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
 
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는 모두 채워야 하며, 표시되는 상자는 비워 둘 수 없습니다. 뷰포트가 비어 있으면 오류가 발생합니다.

예를 들어 이 뷰포트는 뉴욕시를 완전히 포함합니다.

SwiftObjective-CiOS용 Places Swift SDK (미리보기)
let high = CLLocationCoordinate2DMake(40.921628, -73.700051)
let low = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceRectangularLocationOption(high, low)
 
CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087);
CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(high, low);
 
let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087)
let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = AutocompleteFilter(coordinateRegionBias: bias)

origin

목적지까지의 직선 거리를 계산할 출발점 (distanceMeters로 반환됨)입니다. 이 값을 생략하면 직선 거리가 반환되지 않습니다. 위도 및 경도 좌표로 지정해야 합니다.

SwiftObjective-CiOS용 Places Swift SDK (미리보기)
let filter = GMSAutocompleteFilter()
filter.origin =  CLLocation(latitude: 37.395804, longitude: -122.077023)
 
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];

filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude: -122.077023];
 
let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))

regionCode

응답 형식을 지정하는 데 사용되는 지역 코드로, ccTLD ('최상위 도메인') 2자리 값으로 지정됩니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk'(.co.uk)이지만 ISO 3166-1 코드는 'gb'입니다(기술적으로 '그레이트 브리튼 북아일랜드 연합왕국'의 항목에 해당).

잘못된 지역 코드를 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다. 이 매개변수는 관련 법규에 따라 결과에 영향을 미칠 수 있습니다.

sessionToken

세션 토큰은 자동 완성 (신규) 호출을 '세션'으로 추적하는 사용자가 생성한 문자열입니다. 자동 완성 (신규)은 세션 토큰을 사용하여 사용자 자동 완성 검색의 쿼리 및 선택 단계를 결제 목적의 개별 세션으로 그룹화합니다. 자세한 내용은 세션 토큰을 참고하세요.

자동 완성 (신규) 예시

locationRestriction 및 locationBias 사용

자동 완성 (신규)은 기본적으로 IP 편향을 사용하여 검색 지역을 제어합니다. IP 편향의 경우 API는 기기의 IP 주소를 사용하여 결과에 편향을 적용합니다. 원하는 경우 locationRestriction 또는 locationBias를 사용하여 검색할 지역을 지정할 수 있지만 둘 다 사용할 수는 없습니다.

위치 제한은 검색할 지역을 지정합니다. 지정된 영역 밖의 결과는 반환되지 않습니다. 다음 예에서는 위치 제한을 사용하여 요청을 샌프란시스코를 중심으로 반경 5,000m인 원형 위치 제한으로 제한합니다.

SwiftObjective-CiOS용 Places Swift SDK (미리보기)
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))")
        }
      }
    })
 
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.
    }
  }
}];
 
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.
}

위치 편향이 있으면 위치가 편향 역할을 합니다. 즉, 지정된 지역 외부의 결과를 포함하여 지정된 위치 주변의 결과가 반환될 수 있습니다. 다음 예에서는 위치 편향을 사용하도록 이전 요청을 변경합니다.

SwiftObjective-CiOS용 Places Swift SDK (미리보기)
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))")
        }
      }
    })
 
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.
    }
  }
}];
 
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.
}

사용 유형

types 매개변수를 사용하여 요청의 결과를 표 A 및 표 B에 나열된 특정 유형으로 제한합니다. 값 배열을 최대 5개까지 지정할 수 있습니다. 생략하면 모든 유형이 반환됩니다.

다음 예에서는 'Soccer'이라는 검색어 문자열을 지정하고 types 매개변수를 사용하여 결과를 "sporting_goods_store" 유형의 시설로 제한합니다.

SwiftObjective-CiOS용 Places Swift SDK (미리보기)
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))")
        }
      }
    })
 
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.
    }
  }
}];
 
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로 반환합니다.

이 예에서는 원점을 샌프란시스코 중심부로 설정합니다.

SwiftObjective-CiOS용 Places Swift SDK (미리보기)
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))")
        }
      }
    })
 
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.
      }
    }
}];
 
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.
}

기여 분석

지도 없이도 자동 완성 (신규)을 사용할 수 있습니다. 지도를 표시하는 경우에는 반드시 Google 지도를 사용해야 합니다. 지도 없이 자동 완성 (신규) 서비스의 추천을 표시하는 경우 검색창/결과와 인라인으로 표시된 Google 로고를 포함해야 합니다. 자세한 내용은 Google 로고 및 저작자 표시 표시를 참고하세요.