소개
Autocomplete (신규)는 HTTP 요청에 대한 응답으로 장소 예상 검색어와 쿼리 예상 검색어를 반환하는 웹 서비스입니다. 요청에서 검색 영역을 제어하는 텍스트 검색 문자열과 지리적 경계를 지정합니다.
Autocomplete (New)는 입력의 전체 단어 및 하위 문자열을 일치시켜 장소 이름, 주소, Plus Code를 결정할 수 있습니다. 따라서 사용자가 입력할 때 애플리케이션에서 쿼리를 전송하여 즉시 장소 및 쿼리 예상 검색어를 제공할 수 있습니다.
Autocomplete (신규)의 응답에는 두 가지 유형의 예측이 포함될 수 있습니다.
- 장소 예상 검색어: 지정된 입력 텍스트 문자열 및 검색 영역을 기반으로 하는 장소(예: 비즈니스, 주소, 관심 장소)입니다. 장소 예상 검색어는 기본적으로 반환됩니다.
- 쿼리 예상 검색어: 입력 텍스트 문자열 및 검색 영역과 일치하는 쿼리 문자열입니다. 쿼리 예측은 기본적으로 반환되지 않습니다.
includeQueryPredictions요청 파라미터를 사용하여 응답에 쿼리 예측을 추가합니다.
예를 들어 검색 영역을 캘리포니아주 샌프란시스코로 제한하고 부분 사용자 입력인 'Sicilian piz'가 포함된 문자열을 입력으로 사용하여 Autocomplete (신규)를 호출합니다. 그러면 응답에는 'Sicilian Pizza Kitchen'이라는 이름의 레스토랑과 같이 검색 문자열 및 검색 영역과 일치하는 장소 예상 검색어 목록과 장소에 대한 세부정보가 포함됩니다.
반환된 장소 예상 검색어는 사용자가 원하는 장소를 선택하는 데 도움이 되도록 사용자에게 표시됩니다. 장소 세부정보 (신규) 요청을 실행하여 반환된 장소 예상 검색어에 대한 자세한 정보를 가져올 수 있습니다.
응답에는 'Sicilian Pizza & Pasta'와 같이 검색 문자열 및 검색 영역과 일치하는 예상 검색어 목록도 포함될 수 있습니다. 응답의 각 쿼리 예측에는 추천 텍스트 검색 문자열이 포함된 text 필드가 포함됩니다. 이 문자열을 텍스트 검색(신규)의 입력으로 사용하여 더 자세한 검색을 실행합니다.
API 탐색기를 사용하면 실시간 요청을 수행하여 API 및 API 옵션을 숙지할 수 있습니다.
Autocomplete (New) 요청
Autocomplete (New) 요청은 다음 형식의 URL에 대한 HTTP POST 요청입니다.
https://places.googleapis.com/v1/places:autocomplete
POST 요청의 일부로 JSON 요청 본문 또는 헤더에 모든 매개변수를 전달합니다. 예를 들면 다음과 같습니다.
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
지원되는 매개변수
매개변수 |
설명 |
|---|---|
검색할 텍스트 문자열 (전체 단어, 하위 문자열, 장소 이름, 주소, Plus Code)입니다. |
|
|
응답에서 반환할 필드를 지정하는 쉼표로 구분된 목록입니다. |
지정된 기본 유형 중 최대 5개와 일치하는 장소로 결과를 제한합니다. |
|
true인 경우 물리적 위치가 없는 비즈니스(방문 서비스 업체)를 포함합니다. 기본값은 false입니다. |
|
true인 경우 응답에 장소 및 쿼리 예측이 모두 포함됩니다. 기본값은 false입니다. |
|
결과를 제한할 최대 15개의 2자리 국가 코드 배열입니다. |
|
입력 문자열 내에서 커서 위치의 0부터 시작하는 유니코드 문자 오프셋으로, 예측에 영향을 미칩니다. 기본값은 입력 길이입니다. |
|
결과에 사용할 기본 언어 (IETF BCP-47 코드)입니다. 기본값은 Accept-Language 헤더 또는 'en'입니다. |
|
검색결과가 편중되는 영역 (원 또는 직사각형)을 지정하여 영역 외부의 결과를 허용합니다. locationRestriction과 함께 사용할 수 없습니다. |
|
검색 결과를 제한할 영역 (원 또는 직사각형)을 지정합니다. 이 영역 외부의 결과는 제외됩니다. locationBias와 함께 사용할 수 없습니다. |
|
예상 목적지까지의 직선 거리 (distanceMeters)를 계산하는 데 사용되는 출발지 지점 (위도, 경도)입니다. |
|
응답 형식을 지정하고 추천에 편향을 적용하는 데 사용되는 지역 코드입니다 (예: 'uk', 'fr'). |
|
결제 목적으로 자동 완성 호출을 세션으로 그룹화하는 사용자 생성 문자열입니다. |
대답 정보
Autocomplete (New)는 JSON 객체를 응답으로 반환합니다. 응답에서 각 항목의 의미는 다음과 같습니다.
suggestions배열에는 인식된 관련성을 기준으로 순서대로 모든 예상 장소와 쿼리가 포함됩니다. 각 장소는placePrediction필드로 표시되고 각 쿼리는queryPrediction필드로 표시됩니다.placePrediction필드에는 장소 ID 및 텍스트 설명을 포함하여 단일 장소 예측에 대한 세부정보가 포함됩니다.input파라미터에 제공된 사용자 입력과 더 가깝게 일치시키기 위해 장소 예상 검색어의 텍스트 설명에는 장소, 거리, 기타 주소 구성요소의 대체 이름이 포함될 수 있습니다. 이러한 대체 이름은 동일한 장소 ID의 장소 세부정보 결과의displayName및 주소 필드에 반환된 이름과 다를 수 있습니다.- 이 경우 일부 장소의 대체 이름은 사용자 입력과 더 일치하는 이름에 따라
languageCode매개변수를 기반으로 예상되는 언어와 다른 언어로 표시될 수 있습니다.
queryPrediction필드에는 단일 쿼리 예측에 대한 자세한 정보가 포함됩니다.
전체 JSON 객체는 다음과 같은 형식입니다.
{
"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
}]
},
...
}
...]
}필수 매개변수
입력
검색할 텍스트 문자열입니다. 전체 단어 및 하위 문자열, 장소 이름, 주소, Plus Code를 지정합니다. Autocomplete(New) 서비스는 이 문자열을 기반으로 일치 가능성이 있는 항목을 반환하고 감지된 관련성을 기반으로 검색 결과를 정렬합니다.
선택적 매개변수
FieldMask
응답 필드 마스크를 만들어 응답에서 반환할 필드 목록을 지정합니다. HTTP 헤더 X-Goog-FieldMask를 사용하여 응답 필드 마스크를 메서드에 전달합니다.
반환할 추천 필드를 쉼표로 구분한 목록을 지정합니다. 예를 들어 추천의 suggestions.placePrediction.text.text 및 suggestions.queryPrediction.text.text를 검색합니다.
X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
*을 사용해 모든 필드를 가져옵니다.
X-Goog-FieldMask: *
includeFutureOpeningBusinesses
true인 경우 향후 개점할 것으로 예상되는 비즈니스를 반환합니다. 기본값은 false입니다.
includedPrimaryTypes
장소는 표 A 또는 표 B에 나열된 유형 중 하나의 기본 유형만 가질 수 있습니다. 예를 들어 기본 유형은 "mexican_restaurant" 또는 "steak_house"일 수 있습니다.
기본적으로 API는 장소와 연결된 기본 유형 값과 관계없이 input 매개변수를 기반으로 모든 장소를 반환합니다. includedPrimaryTypes 매개변수를 전달하여 결과를 특정 기본 유형으로 제한합니다.
이 매개변수를 사용하여 표 A 또는 표 B에서 최대 5개의 유형 값을 지정합니다. 장소가 지정된 기본 유형 값 중 하나와 일치해야 응답에 포함됩니다.
이 매개변수에는 (regions) 또는 (cities) 중 하나가 포함될 수도 있습니다. (regions) 유형 컬렉션은 인근 지역 및 우편번호와 같은 지역 또는 구역을 필터링합니다. (cities) 유형 컬렉션은 Google에서 도시로 식별하는 장소를 필터링합니다.
다음과 같은 경우 요청이 INVALID_REQUEST 오류로 거부됩니다.
- 여섯 개 이상의 유형이 지정되었습니다.
(cities)또는(regions)외에 유형이 지정됩니다.- 인식할 수 없는 유형이 지정된 경우
includePureServiceAreaBusinesses
true로 설정하면 응답에 고객을 직접 방문하거나 고객에게 배달하지만 실제 비즈니스 위치가 없는 비즈니스가 포함됩니다. false로 설정하면 API는 실제 비즈니스 위치가 있는 비즈니스만 반환합니다.
includeQueryPredictions
true인 경우 응답에 장소 및 쿼리 예측이 모두 포함됩니다. 기본값은 false입니다. 즉, 응답에 장소 예상만 포함됩니다.
includedRegionCodes
최대 15개의 ccTLD('최상위 도메인') 2자리 값 배열로 지정된 지정된 지역 목록의 결과만 포함합니다. 생략하면 응답에 제한이 적용되지 않습니다. 예를 들어 리전을 독일과 프랑스로 제한하려면 다음을 실행합니다.
"includedRegionCodes": ["de", "fr"]
locationRestriction와 includedRegionCodes를 모두 지정하면 두 설정의 교차 영역에 결과가 표시됩니다.
inputOffset
input의 커서 위치를 나타내는 0부터 시작하는 유니코드 문자 오프셋입니다.
커서 위치는 반환되는 예상 검색어에 영향을 줄 수 있습니다. 비어 있으면 기본값은 input의 길이입니다.
languageCode
결과를 반환할 기본 언어입니다. input에 사용된 언어가 languageCode에 지정된 값과 다르거나 반환된 장소에 현지 언어에서 languageCode로의 번역이 없는 경우 결과가 여러 언어로 표시될 수 있습니다.
- IETF BCP-47 언어 코드를 사용하여 기본 언어를 지정해야 합니다.
-
languageCode를 제공하지 않으면 API는Accept-Language헤더에 지정된 값을 사용합니다. 둘 다 지정되지 않으면 기본값은en입니다. 잘못된 언어 코드를 지정하면 API에서INVALID_ARGUMENT오류를 반환합니다. - 기본 언어는 API가 반환하도록 선택하는 결과 집합과 반환되는 순서에 약간의 영향을 미칩니다. 이는 API의 맞춤법 오류 수정 기능에도 영향을 미칩니다.
-
장소 예상 검색어는 각 요청의 사용자 입력에 따라 다르게 형식이 지정됩니다.
-
input매개변수의 일치하는 용어가 먼저 선택됩니다. 가능한 경우languageCode매개변수로 표시된 언어 환경설정에 맞는 이름이 사용되고, 그렇지 않으면 사용자 입력과 가장 일치하는 이름이 사용됩니다. -
장소 이름은
languageCode매개변수로 표시된 언어 이외의 언어로 된 이름을 포함하여input매개변수의 용어와 일치하도록 대체 이름을 사용하여 형식을 지정할 수 있습니다. -
상세 주소는
input매개변수의 용어와 일치하는 용어가 선택된 후에만 현지 언어로, 가능하면 사용자가 읽을 수 있는 스크립트로 형식이 지정됩니다. -
다른 모든 주소는
input매개변수의 용어와 일치하는 용어가 선택된 후 기본 언어로 반환됩니다. 선호하는 언어로 된 이름이 없는 경우 API는 가장 일치하는 이름을 사용합니다.
-
locationBias 또는 locationRestriction
locationBias 또는 locationRestriction 중 하나를 지정하여 검색 영역을 정의할 수 있지만 둘 다 지정할 수는 없습니다. locationRestriction은 결과가 포함되어야 하는 지역을 지정하고 locationBias은 결과가 근처에 있어야 하지만 해당 지역 외부에 있을 수 있는 지역을 지정한다고 생각하면 됩니다.
locationBias
검색할 영역을 지정합니다. 이 위치는 상세 검색으로 사용됩니다. 즉, 지정된 지역 외부의 결과를 포함하여 지정된 위치 주변의 결과가 반환될 수 있습니다.
locationRestriction
검색할 영역을 지정합니다. 지정된 영역 외부의 결과는 반환되지 않습니다.
locationBias 또는 locationRestriction 리전을 직사각형 표시 영역 또는 원으로 지정합니다.
원은 중심점과 반지름(미터)으로 정의됩니다. 반경은 0.0~50000.0 사이여야 합니다. 기본값은 0.0입니다.
locationRestriction의 경우 반경을 0.0보다 큰 값으로 설정해야 합니다. 그렇지 않으면 요청에서 결과가 반환되지 않습니다.예를 들면 다음과 같습니다.
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
직사각형은 위도-경도 표시 영역으로, 대각선으로 반대되는 두 개의
low및 높은 지점으로 표시됩니다. 표시 영역은 경계를 포함하는 닫힌 영역으로 간주됩니다. 위도 경계는 -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를 모두 채워야 하며 표시된 상자는 비워 둘 수 없습니다. 표시 영역이 비어 있으면 오류가 발생합니다.예를 들어 다음 표시 영역은 뉴욕시를 완전히 둘러쌉니다.
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
origin
목적지까지의 직선 거리를 계산할 출발지입니다(distanceMeters로 반환됨). 이 값을 생략하면 직선 거리가 반환되지 않습니다. 위도 및 경도 좌표로 지정해야 합니다.
"origin": { "latitude": 40.477398, "longitude": -74.259087 }
regionCode
응답 형식을 지정하는 데 사용되는 지역 코드로, ccTLD('최상위 도메인') 2자리 값으로 지정됩니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk'(.co.uk)이지만 ISO 3166-1 코드는 'gb'입니다(엄밀히 말하면 'The United Kingdom of Great Britain and Northern Ireland').
추천은 지역 코드를 기반으로 편향됩니다. Google에서는 사용자의 지역 설정에 따라 regionCode를 설정할 것을 권장합니다.
잘못된 지역 코드를 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다. 이 매개변수는 관련 법률에 따라 결과에 영향을 미칠 수 있습니다.
regionCode를 설정하면 해당 지역 내의 예측에서 추천 텍스트의 국가 이름이 생략될 수 있습니다. 즉, structuredFormat.secondaryText가 없을 수 있습니다. 따라서 애플리케이션이 secondaryText가 정의되지 않았거나 누락된 경우를 처리하는지 확인하세요.
sessionToken
세션 토큰은 Autocomplete (New) 호출을 '세션'으로 추적하는 사용자 생성 문자열입니다. Autocomplete(신규)는 세션 토큰을 사용하여 사용자 자동 완성 검색의 쿼리 및 선택 단계를 결제 목적의 개별 세션으로 그룹화합니다. 자세한 내용은 세션 토큰을 참고하세요.
결과 편향을 위한 매개변수 선택
자동 완성 (신규) 매개변수는 검색 결과에 다르게 영향을 미칠 수 있습니다. 다음 표에서는 의도한 결과에 따른 매개변수 사용에 대한 권장사항을 제공합니다.| 매개변수 | 사용 권장사항 |
|---|---|
regionCode
|
사용자의 지역 설정에 따라 설정됩니다. |
includedRegionCodes
|
지정된 리전 목록으로 결과를 제한하도록 설정합니다. |
locationBias
|
특정 지역 또는 그 주변의 결과를 선호하는 경우에 사용합니다. 해당하는 경우 사용자가 보고 있는 지도의 표시 영역으로 지역을 정의합니다. |
locationRestriction
|
지역 외부의 결과가 반환되지 않아야 하는 경우에만 사용합니다. |
origin
|
각 예측에 대한 직선 거리를 사용하려는 경우에 사용합니다. |
Autocomplete (New) 예시
locationRestriction을 사용하여 검색을 특정 지역으로 제한
locationRestriction는 검색할 영역을 지정합니다. 지정된 영역 외부의 결과는 반환되지 않습니다. 다음 예시에서는 locationRestriction를 사용하여 샌프란시스코를 중심으로 반경 5, 000m의 원으로 요청을 제한합니다.
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
지정된 영역 내의 모든 결과는 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" ] } }, /.../ ] }
locationRestriction를 사용하여 검색을 직사각형 표시 영역으로 제한할 수도 있습니다. 다음 예에서는 요청을 샌프란시스코 시내로 제한합니다.
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
결과는 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" ] } } ] }
locationBias를 사용하여 특정 지역으로 검색 편향
locationBias를 사용하면 위치가 편향으로 작용합니다. 즉, 지정된 지역 외부의 결과를 포함하여 지정된 위치 주변의 결과가 반환될 수 있습니다. 다음 예에서는 샌프란시스코 시내로 요청을 편향합니다.
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
이제 결과에는 5, 000미터 반경 외부의 결과를 포함하여 더 많은 항목이 포함됩니다.
{ "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" ] } }, ... ] }
locationBias를 사용하여 검색을 직사각형 표시 영역으로 편향시킬 수도 있습니다. 다음 예에서는 요청을 샌프란시스코 시내로 제한합니다.
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
직사각형 표시 영역 내의 검색 결과가 응답에 표시되지만 상세 검색으로 인해 일부 결과가 정의된 경계를 벗어납니다. 결과는 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" ] } }, /.../ ] }
includedPrimaryTypes 사용
includedPrimaryTypes 매개변수를 사용하여 표 A, 표 B에서 최대 5개의 유형 값을 지정하거나 (regions)만 지정하거나 (cities)만 지정합니다. 장소가
응답에 포함되려면 지정된 기본 유형 값 중 하나와
일치해야 합니다.
다음 예에서는 input 문자열을 'Soccer'로 지정하고 includedPrimaryTypes 매개변수를 사용하여 결과를 "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
includedPrimaryTypes 매개변수를 생략하면 결과에 "athletic_field"와 같이 원하지 않는 유형의 시설이 포함될 수 있습니다.
쿼리 예측 요청
쿼리 예측은 기본적으로 반환되지 않습니다. includeQueryPredictions 요청 파라미터를 사용하여 응답에 쿼리 예측을 추가합니다. 예를 들면 다음과 같습니다.
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
이제 suggestions 배열에는 위의 응답 정보에 표시된 것처럼 장소 예상 검색어와 쿼리 예상 검색어가 모두 포함됩니다. 각 쿼리 예측에는 추천 텍스트 검색 문자열이 포함된 text 필드가 포함됩니다. 텍스트 검색 (신규) 요청을 실행하여 반환된 예상 검색어에 대한 자세한 정보를 확인할 수 있습니다.
원본 사용
이 예에서는 요청에 origin를 위도 및 경도 좌표로 포함합니다. origin를 포함하면 Autocomplete(신규)는 origin에서 목적지까지의 직선 거리가 포함된 distanceMeters 필드를 응답에 포함합니다. 이 예시에서는 출발지를 샌프란시스코 중심으로 설정합니다.
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
이제 응답에 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 } } ] }
향후 영업 예정인 비즈니스 찾기
다음 예는 아이다호주 뉴메도우즈에서 향후 개업하는 비즈니스에 대한 Autocomplete (New) 요청을 보여줍니다.
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"
응답에는 장소에 대한 세부정보가 포함되지만 개장일은 포함되지 않습니다.
{ "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" ] } } ] }
응답에 거리가 누락됨
경우에 따라 origin가 요청에 포함되어 있어도 distanceMeters가 응답 본문에서 누락됩니다. 이는 다음과 같은 시나리오에서 발생할 수 있습니다.
distanceMeters은route예측에 포함되지 않습니다.distanceMeters는 값이0인 경우 포함되지 않습니다. 이는 제공된origin위치에서 1미터 미만 떨어진 예측의 경우입니다.
파싱된 객체에서 distanceMeters 필드를 읽으려고 시도하는 클라이언트 라이브러리는 값이 0인 필드를 반환합니다. 사용자에게 오해를 주지 않으려면 사용자에게 거리를 0으로 표시하지 마세요.
Autocomplete (New) 최적화
이 섹션에서는 Autocomplete (New) 서비스를 최대한 활용하는 데 도움이 되는 권장사항을 설명합니다.
다음은 일반 가이드라인입니다.
- 작동하는 사용자 인터페이스를 개발하는 가장 빠른 방법은 Maps JavaScript API 자동 완성 (신규) 위젯, Android용 Places SDK 자동 완성 (신규) 위젯 또는 iOS용 Places SDK 자동 완성 (신규) 위젯을 사용하는 것입니다.
- 기본적인 Autocomplete (New) 데이터 필드를 처음부터 이해합니다.
- 위치 상세 검색 및 위치 제한 필드는 선택사항이지만 자동 완성 성능에 상당한 영향을 미칠 수 있습니다.
- API가 오류를 반환하는 경우 오류 처리를 사용하여 앱의 성능이 적절히 저하되도록 합니다.
- 선택된 항목이 없을 때 앱에서 처리하고 사용자에게 계속할 수 있는 방법을 제공하도록 합니다.
비용 최적화 권장사항
기본 비용 최적화
Autocomplete(New) 서비스 사용 비용을 최적화하려면 Place Details(New)(장소 세부정보) 및 Autocomplete(New) 위젯에서 필드 마스크를 사용하여 필요한 Autocomplete(New) 데이터 필드만 반환하세요.
고급 비용 최적화
SKU: Autocomplete Request 가격 책정에 액세스하고 Place Details (New) 대신 선택된 장소에 대한 Geocoding API 결과를 요청하려면 Autocomplete (New)를 프로그래매틱 방식으로 구현해 보세요. Geocoding API와 연결된 요청당 가격은 다음 두 조건이 모두 충족되는 경우 세션당(세션 기반) 가격보다 비용 효과적입니다.
- 사용자가 선택한 장소의 위도와 경도 또는 주소만 필요한 경우 Geocoding API는 장소 세부정보 (신규) 호출보다 낮은 비용으로 이 정보를 제공합니다.
- 사용자가 평균 네 개 이하의 Autocomplete (New) 예상 검색어 요청 내에서 자동 완성 예상 검색어를 선택하면 요청당 가격이 세션당 가격보다 비용 효과적일 수 있습니다.
| 애플리케이션에 필요한 항목 | 사용자가 예상 검색어를 선택하기 전의 평균 Autocomplete (신규) 요청 수 | 권장되는 구현 |
|---|---|---|
| 장소 이름, 비즈니스 상태, 영업시간 등 주소 및 위치 이외의 장소 세부정보 | 임의의 숫자 | 세션 기반 자동 완성 (신규) 및 장소 세부정보 (신규) |
| 선택된 예상 검색어의 주소 및 위도/경도만 | 4개 이하 | Geocoding API를 사용하는 요청당 Autocomplete (New) |
| 선택된 예상 검색어의 주소 및 위도/경도만 | 4개 초과 | 주소 전용 애플리케이션을 위한 세션 기반 Autocomplete (New) |
Autocomplete (신규)의 사용 성능에 따라 Geocoding API가 장소 세부정보 (신규)보다 애플리케이션에 비용 효과적일 수 있습니다. 모든 애플리케이션의 Autocomplete (New) 효율성은 사용자가 입력하는 내용, 애플리케이션이 사용되는 위치, 성능 최적화 권장사항이 구현되었는지 여부에 따라 다릅니다.
표의 평균 요청 수를 확인하려면 애플리케이션에서 Autocomplete (New) 예상 검색어를 선택하기 전에 사용자가 평균적으로 입력하는 문자 수를 분석하세요.
세션 기반 자동 완성 (New) 및 장소 세부정보 (New)
세션 기반 Autocomplete (New)를 장소 세부정보 (New)와 함께 사용
애플리케이션에 장소 이름, 비즈니스 상태, 영업시간과 같은 장소 세부정보 (신규)가 필요하므로 Autocomplete (New) 구현에서는 요청하는 장소 데이터 필드에 따라 세션당 세션 토큰(프로그래매틱 방식 또는 JavaScript, Android, iOS 위젯에 내장됨)과 관련 장소 SKU를 사용해야 합니다.1
위젯 구현
세션 관리는 JavaScript, Android 또는 iOS에 자동으로 내장됩니다. 여기에는 선택된 예상 검색어에 대한 Autocomplete (New) 요청 및 장소 세부정보 (New) 요청이 모두 포함됩니다. 필요한 Autocomplete (New) 데이터 필드만 요청하도록 하려면 fields 파라미터를 지정해야 합니다.
프로그래매틱 구현
Autocomplete (New) 요청에 세션 토큰을 사용합니다. 선택된 예상 검색어에 대해 장소 세부정보 (신규)를 요청할 때 다음 매개변수를 포함합니다.
- Autocomplete (신규) 응답의 장소 ID
- Autocomplete (신규) 요청에 사용되는 세션 토큰
- 필요한 Autocomplete (신규) 데이터 필드를 지정하는
fields매개변수
Geocoding API를 사용하는 요청당 Autocomplete (New)
세션 토큰 없이 프로그래매틱 방식으로 Autocomplete (New)를 구현하고 선택한 장소 예상 검색어에 대해 Geocoding API 호출
Geocoding API는 주소 및 위도/경도 좌표를 제공합니다.
Autocomplete Requests를 4회 요청하고 선택된 장소 예상 검색어에 대한 Geocoding API 호출을 1회 수행하는 데 드는 비용은 세션당 Autocomplete (New) 비용보다 적습니다.1
성능 권장사항을 사용하여 사용자가 훨씬 적은 수의 문자로 원하는 예상 검색어를 가져올 수 있도록 도와주세요.
주소 전용 애플리케이션을 위한 세션 기반 Autocomplete (New)
세션 기반 Autocomplete (New)를 장소 세부정보 (New)와 함께 사용
사용자가 Autocomplete (신규) 예상 검색어를 선택하기 전에 예상되는 평균 요청 수가 세션당 가격 책정 비용을 초과하므로 Autocomplete (신규) 구현에서는 Autocomplete (신규) 요청과 연결된 장소 세부정보 (신규) 요청 모두에 세션 토큰을 사용해야 합니다.
세션당
1
위젯 구현
세션 관리는 JavaScript, Android 또는 iOS에 자동으로 내장됩니다. 여기에는 선택된 예상 검색어에 대한 자동 완성 (신규) 요청 및 장소 세부정보 (신규) 요청이 모두 포함됩니다. 필요한 필드만 요청하도록 하려면 fields 매개변수를 지정해야 합니다.
프로그래매틱 구현
Autocomplete (New) 요청에 세션 토큰을 사용합니다.
선택된 예상 검색어에 대해 장소 세부정보 (신규)를 요청할 때 다음 매개변수를 포함합니다.
- Autocomplete (신규) 응답의 장소 ID
- Autocomplete (신규) 요청에 사용되는 세션 토큰
- 주소 및 도형과 같은 필드를 지정하는
fields매개변수
Autocomplete (New) 요청 지연 고려
사용자가 처음 3~4자를 입력할 때까지 Autocomplete (New) 요청을 지연하는 것과 같은 전략을 채택하여 애플리케이션에서 요청하는 횟수를 줄일 수 있습니다. 예를 들어 사용자가 세 번째 문자를 입력한 후 각 문자에 대해 Autocomplete (New) 요청을 하는 경우 사용자가 7개의 문자를 입력한 다음 Geocoding API 요청을 1회 하는 예상 검색어를 선택하면 총비용은 Autocomplete (New) Per Request 4회 + Geocoding에 대한 비용이 됩니다.1
요청을 지연하면 평균 프로그래매틱 요청 수가 네 개 미만이 될 수 있는 경우 Geocoding API를 사용한 고성능 Autocomplete (New) 구현을 위한 안내를 따르세요. 키를 입력할 때마다 예상 검색어가 표시될 것이라고 예상하는 사용자는 요청 지연을 지연 시간으로 인식할 수 있습니다.
성능 권장사항을 사용하여 사용자가 더 적은 수의 문자로 원하는 예상 검색어를 가져올 수 있도록 도와주세요.
-
비용은 Google Maps Platform 가격 목록을 참고하세요.
성능 권장사항
다음 가이드라인에서는 Autocomplete (New) 성능을 최적화하는 방법을 설명합니다.
- Autocomplete (New) 구현에 국가별 제한사항, 위치 상세 검색, (프로그래매틱 구현의 경우) 언어 환경설정을 추가합니다. 위젯은 사용자의 브라우저 또는 휴대기기에서 언어 환경설정을 선택하므로 언어 환경설정이 필요하지 않습니다.
- Autocomplete (New)에 지도와 함께 제공된 경우 지도 표시 영역별로 위치를 상세 검색할 수 있습니다.
- 예상 검색어 중 원하는 결과 주소가 없어 사용자가 자동 완성 (신규) 예상 검색어 중 하나를 선택하지 않는 경우 원래 사용자 입력을 재사용하여 더 관련성 높은 결과를 얻을 수 있습니다.
- 사용자가 주소 정보만 입력할 것으로 예상되는 경우 Geocoding API 호출 시 원래 사용자 입력을 재사용합니다.
- 사용자가 이름 또는 주소로 특정 장소에 대한 쿼리를 입력할 것으로 예상되는 경우 장소 세부정보 (신규) 요청을 사용합니다. 특정 지역에서만 결과가 예상되는 경우 위치 상세 검색을 사용합니다.
- 건물 내 특정 호수 또는 아파트 주소와 같은 하위 구내 주소를 입력하는 사용자 예를 들어 체코 주소인 'Stroupeсnického 3191/17, Praha'를 바탕으로 Autocomplete (New)에서 부분 예측이 이루어집니다.
- 사용자가 뉴욕시의 '23-30 29th St, Queens' 또는 하와이 카우아이섬의 '47-380 Kamehameha Hwy, Kaneohe'처럼 도로 구간 접두사가 있는 주소를 입력하는 경우
위치 편향
location 매개변수와 radius 매개변수를 전달하여 특정 지역에 편중된 결과를 얻습니다. 이렇게 하면 Autocomplete (New)에서 정의된 영역 내의 결과를 우선적으로 표시합니다. 정의된 영역 밖의 결과가 표시될 수도 있습니다. includedRegionCodes 매개변수를 사용하여 지정된 국가 내의 장소만 표시하도록 결과를 필터링할 수 있습니다.
위치 제한
locationRestriction 매개변수를 전달하여 결과를 특정 지역으로 제한합니다.
locationRestriction 매개변수를 추가하여 location 및 radius 매개변수로 정의된 지역으로 결과를 제한할 수도 있습니다. 이렇게 하면 Autocomplete (New)가 해당 지역 내의 결과만 반환합니다.
기능을 사용해 보세요.
API 탐색기를 사용하면 샘플 요청을 수행하여 API 및 API 옵션을 숙지할 수 있습니다.
페이지 오른쪽에서 API 아이콘 api을 선택합니다.
원하는 경우 요청 매개변수를 수정합니다.
실행 버튼을 선택합니다. 대화상자에서 요청에 사용할 계정을 선택합니다.
I API 탐색기 패널에서 전체 화면 아이콘 전체 화면을 선택하여 API 탐색기 창을 펼칩니다.