이 페이지는 Cloud Translation API를 통해 번역되었습니다.

자동 완성 (신규)

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

유럽 경제 지역 (EEA) 개발자

소개

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

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

Autocomplete (신규)의 응답에는 다음 두 가지 유형의 예상 검색어가 포함될 수 있습니다.

장소 예측: 지정된 입력 텍스트 문자열 및 검색 영역을 기반으로 한 장소(예: 비즈니스, 주소, 관심 장소) 장소 예상 검색어는 기본적으로 반환됩니다.
검색어 예측: 입력 텍스트 문자열 및 검색 영역과 일치하는 검색어 문자열입니다. 쿼리 예측은 기본적으로 반환되지 않습니다. includeQueryPredictions 요청 매개변수를 사용하여 응답에 쿼리 예측을 추가합니다.

예를 들어 검색 영역이 캘리포니아주 샌프란시스코로 제한된 상태에서 부분 사용자 입력인 'Sicilian piz'가 포함된 문자열을 입력으로 사용하여 Autocomplete (신규)를 호출합니다. 그러면 응답에 검색 문자열 및 검색 영역과 일치하는 장소 예측 목록이 포함됩니다. 예를 들어 'Sicilian Pizza Kitchen'이라는 레스토랑과 장소에 관한 세부정보가 포함됩니다.

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

또한 응답에는 검색 문자열 및 검색어와 일치하는 쿼리 예측 목록이 포함될 수 있습니다(예: '시칠리아 피자 & 파스타'). 대답의 각 쿼리 예측에는 추천 텍스트 검색 문자열이 포함된 text 필드가 포함됩니다. 이 문자열을 텍스트 검색 (신규)의 입력으로 사용하여 더 자세한 검색을 실행합니다.

API 탐색기를 사용하면 API와 API 옵션을 숙지할 수 있도록 라이브 요청을 할 수 있습니다.

사용해 보기

Autocomplete (신규) 요청

Autocomplete (New) 요청은 다음과 같은 형식의 URL에 대한 HTTP POST 요청입니다.

https://places.googleapis.com/v1/places:autocomplete

JSON 요청 본문 또는 헤더에 모든 매개변수를 전달합니다(POST 요청의 일부). 예를 들면 다음과 같습니다.

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

지원되는 매개변수

매개변수	설명
`input`*	검색할 텍스트 문자열 (전체 단어, 하위 문자열, 장소 이름, 주소, Plus Code)입니다.
`FieldMask` (HTTP 헤더)	응답에서 반환할 필드를 지정하는 쉼표로 구분된 목록입니다.
`includedPrimaryTypes`	최대 5개의 지정된 기본 유형 중 하나와 일치하는 장소로 결과를 제한합니다.
`includePureServiceAreaBusinesses`	true인 경우 오프라인 매장이 없는 비즈니스(방문 서비스 업체)를 포함합니다. 기본값은 false입니다.
`includeQueryPredictions`	true인 경우 응답에 장소 및 쿼리 예측을 모두 포함합니다. 기본값은 false입니다.
`includedRegionCodes`	결과를 제한할 최대 15개의 2자리 국가 코드 배열입니다.
`inputOffset`	입력 문자열 내 커서 위치의 0부터 시작하는 유니코드 문자 오프셋으로, 예측에 영향을 미칩니다. 기본값은 입력 길이입니다.
`languageCode`	결과의 기본 언어 (IETF BCP-47 코드)입니다. 기본값은 Accept-Language 헤더 또는 'en'입니다.
`locationBias`	검색 결과가 편향될 영역 (원 또는 직사각형)을 지정하여 영역 외부의 결과를 허용합니다. locationRestriction과 함께 사용할 수 없습니다.
`locationRestriction`	검색 결과를 제한할 영역 (원 또는 직사각형)을 지정합니다. 이 영역 밖의 결과는 제외됩니다. locationBias와 함께 사용할 수 없습니다.
`origin`	예측된 목적지까지의 직선 거리 (distanceMeters)를 계산하는 데 사용되는 원점 (위도, 경도)입니다.
`regionCode`	응답의 형식을 지정하고 추천에 편향을 주기 위해 사용되는 지역 코드입니다 (예: 'uk', 'fr').
`sessionToken`	결제 목적으로 자동 완성 호출을 세션으로 그룹화하는 사용자 생성 문자열입니다.

* 는 필수 입력란을 나타냅니다.

응답 정보

자동 완성 (신규)은 JSON 객체를 응답으로 반환합니다. 응답에서 각 항목의 의미는 다음과 같습니다.

suggestions 배열에는 인식된 관련성을 기준으로 모든 예측 장소와 쿼리가 순서대로 포함됩니다. 각 장소는 placePrediction 필드로 표시되고 각 쿼리는 queryPrediction 필드로 표시됩니다.
placePrediction 필드에는 장소 ID, 텍스트 설명 등 단일 장소 예측에 관한 자세한 정보가 포함됩니다.
queryPrediction 필드에는 단일 쿼리 예측에 관한 자세한 정보가 포함됩니다.

참고: 자동 완성 (신규)은 요청에 따라 placePredictions, queryPredictions 또는 조합으로 총 5개의 예측을 반환합니다. 요청에서 includeQueryPredictions를 설정하지 않으면 응답에 최대 5개의 placePredictions가 포함됩니다. 요청에서 includeQueryPredictions를 설정하면 응답에 placePredictions 및 queryPredictions의 조합으로 최대 5개의 예측이 포함됩니다.

전체 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: *
```
includedPrimaryTypes

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

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

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

이 매개변수에는 (regions) 또는 (cities) 중 하나가 대신 포함될 수도 있습니다. (regions) 유형 컬렉션은 동네, 우편번호와 같은 지역 또는 구역을 필터링합니다. (cities) 유형 컬렉션은 Google에서 도시로 식별하는 장소를 필터링합니다.

다음과 같은 경우 요청이 INVALID_REQUEST 오류로 거부됩니다.
- 6개 이상의 유형이 지정되었습니다.
- (cities) 또는 (regions) 외에 다른 유형이 지정됩니다.
- 인식할 수 없는 유형이 지정됩니다.
참고: includedPrimaryTypes 매개변수는 장소의 기본 유형에만 적용되며 장소와 연결된 모든 유형에 적용되지는 않습니다. 모든 장소에는 기본 유형이 있지만 모든 기본 유형이 Places API (New)에서 지원되는 것은 아닙니다. 지원되는 유형에는 표 A 또는 표 B에 나열된 유형이 포함됩니다.
includePureServiceAreaBusinesses

true로 설정된 경우 고객을 직접 방문하거나 고객에게 직접 서비스를 제공하지만 실제 비즈니스 위치가 없는 비즈니스가 대답에 포함됩니다. false로 설정하면 API는 실제 비즈니스 위치가 있는 비즈니스만 반환합니다.
includeQueryPredictions

true인 경우 응답에 장소와 쿼리 예측이 모두 포함됩니다. 기본값은 false이며, 이는 응답에 장소 예측만 포함됨을 의미합니다.
includedRegionCodes

최대 15개의 ccTLD ('최상위 도메인') 2자리 값 배열로 지정된 지정된 지역 목록의 결과만 포함합니다. 생략하면 응답에 제한이 적용되지 않습니다. 예를 들어 지역을 독일과 프랑스로 제한하려면 다음을 실행합니다.
```
    "includedRegionCodes": ["de", "fr"]
```
locationRestriction와 includedRegionCodes을 모두 지정하면 결과가 두 설정의 교차 영역에 위치합니다.

참고: 국가 코드가 포함된 예기치 않은 결과가 반환되면 원하는 국가, 종속 지역, 특별 관심 지역이 포함된 코드를 사용하고 있는지 확인하세요. 코드 정보는 위키백과: ISO 3166 국가 코드 목록 또는 ISO 온라인 탐색 플랫폼에서 확인할 수 있습니다.
inputOffset

input의 커서 위치를 나타내는 0부터 시작하는 유니코드 문자 오프셋입니다. 커서 위치에 따라 반환되는 예측이 달라질 수 있습니다. 비어 있으면 기본값은 input의 길이입니다.

참고: 제한된 미리보기 출시의 초기 버전에서 이 속성은 predictionTermOffset라고 했습니다.
languageCode

결과를 반환할 기본 언어입니다. input에 사용된 언어가 languageCode에 지정된 값과 다르거나 반환된 장소에 현지 언어에서 languageCode로의 번역이 없는 경우 결과가 여러 언어로 표시될 수 있습니다.
- IETF BCP-47 언어 코드를 사용하여 선호하는 언어를 지정해야 합니다.
- languageCode이 제공되지 않으면 API는 Accept-Language 헤더에 지정된 값을 사용합니다. 둘 다 지정되지 않으면 기본값은 en입니다. 잘못된 언어 코드를 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다.
- 기본 언어는 API가 반환하기로 선택한 결과 집합과 반환되는 순서에 약간의 영향을 미칩니다. 맞춤법 오류를 수정하는 API의 기능에도 영향을 미칩니다.
- API는 사용자 입력이 반영되는 동시에 사용자와 현지인이 읽을 수 있는 도로명 주소를 제공하려고 시도합니다. 장소 예측은 각 요청의 사용자 입력에 따라 다르게 형식이 지정됩니다.
  - input 매개변수의 일치하는 용어는 먼저 사용 가능한 경우 languageCode 매개변수로 표시된 언어 환경설정과 일치하는 이름을 사용하여 선택되고, 그렇지 않은 경우 사용자 입력과 가장 일치하는 이름을 사용합니다.
  - 거리 주소는 현지 언어로, 가능하면 사용자가 읽을 수 있는 스크립트로 서식이 지정됩니다. 이는 input 매개변수의 용어와 일치하는 용어가 선택된 후에만 가능합니다.
  - 다른 모든 주소는 input 매개변수의 용어와 일치하도록 용어가 선택된 후 기본 언어로 반환됩니다. 선호하는 언어로 이름을 사용할 수 없는 경우 API는 가장 일치하는 이름을 사용합니다.
locationBias 또는 locationRestriction

locationBias 또는 locationRestriction를 지정하여 검색 영역을 정의할 수 있지만 둘 다 지정할 수는 없습니다. locationRestriction는 결과가 있어야 하는 지역을 지정하고 locationBias는 결과가 있어야 하는 지역을 지정하지만 영역 외부에 있을 수 있습니다.

참고: locationBias과 locationRestriction을 모두 생략하면 자동 완성 (신규)에서 기본적으로 IP 바이어싱을 사용합니다. IP 바이어싱을 사용하면 자동 완성 (신규)에서 기기의 IP 주소를 사용하여 결과를 바이어싱합니다.
- 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' (기술적으로 '영국' 법인의 경우)입니다.

추천은 지역 코드를 기반으로 편향되기도 합니다. Google에서는 사용자의 지역 선호도에 따라 regionCode를 설정할 것을 권장합니다.

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

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

결과에 편향을 줄 매개변수 선택

자동 완성 (신규) 매개변수는 검색 결과에 다르게 영향을 줄 수 있습니다. 다음 표에는 의도한 결과에 따른 매개변수 사용 권장사항이 나와 있습니다.

매개변수	사용 권장사항
`regionCode`	사용자의 지역 설정에 따라 설정됩니다.
`includedRegionCodes`	결과를 지정된 리전 목록으로 제한하도록 설정합니다.
`locationBias`	특정 지역 내 또는 주변의 결과가 선호되는 경우 사용합니다. 해당하는 경우 사용자가 보고 있는 지도의 표시 영역으로 지역을 정의합니다.
`locationRestriction`	지역 외부의 결과가 반환되지 않아야 하는 경우 only를 사용합니다.
`origin`	각 예측까지의 직선 거리가 필요한 경우 사용합니다. 참고: 일부 예측에서는 거리를 사용할 수 없습니다. 응답에 거리가 누락됨을 참고하세요.

Autocomplete (신규) 예

locationRestriction을 사용하여 검색을 특정 지역으로 제한

참고: 자동 완성 (신규)은 기본적으로 IP 바이어스를 사용하여 검색 영역을 제어합니다. IP 바이어싱을 사용하면 자동 완성 (신규)에서 기기의 IP 주소를 사용하여 결과를 바이어싱합니다. 선택적으로 locationRestriction 또는 locationBias를 사용하여 검색할 영역을 지정할 수 있지만 둘 다 사용할 수는 없습니다.

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

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 문자열을 지정하고 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 필드가 포함됩니다. 텍스트 검색 (신규) 요청을 통해 반환된 쿼리 예측에 대한 자세한 정보를 확인할 수 있습니다.

참고: includedRegionCodes 매개변수가 설정된 경우 쿼리 예측이 반환되지 않습니다.

출처 사용

이 예에서는 origin를 위도 및 경도 좌표로 요청에 포함합니다. origin를 포함하면 Autocomplete (New)에서 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
      }
    }
  ]
}

응답에서 거리가 누락됨

origin이 요청에 포함되어 있어도 distanceMeters이 응답 본문에서 누락되는 경우가 있습니다. 다음과 같은 경우 이 문제가 발생할 수 있습니다.

distanceMeters은 route 예측에 포함되지 않습니다.
distanceMeters는 값이 0인 경우 포함되지 않습니다. 이는 제공된 origin 위치에서 1미터 미만인 예측의 경우입니다.

파싱된 객체에서 distanceMeters 필드를 읽으려고 시도하는 클라이언트 라이브러리는 값이 0인 필드를 반환합니다. 사용자를 혼동시키지 않으려면 사용자에게 0 거리를 표시하지 마세요.

사용해 보기

API 탐색기를 사용하면 API 및 API 옵션에 익숙해질 수 있도록 샘플 요청을 할 수 있습니다.

페이지 오른쪽에 있는 API 아이콘 api을 선택합니다.
원하는 경우 요청 매개변수를 수정합니다.
실행 버튼을 선택합니다. 대화상자에서 요청을 보낼 때 사용할 계정을 선택합니다.
API 탐색기 패널에서 전체 화면 아이콘 전체 화면을 선택하여 API 탐색기 창을 펼칩니다.

자동 완성 (신규)

소개

Autocomplete (신규) 요청

지원되는 매개변수

응답 정보

필수 매개변수

입력

선택적 매개변수

FieldMask

includedPrimaryTypes

includePureServiceAreaBusinesses

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias 또는 locationRestriction

locationBias

locationRestriction

origin

regionCode

sessionToken

결과에 편향을 줄 매개변수 선택

Autocomplete (신규) 예

locationRestriction을 사용하여 검색을 특정 지역으로 제한

locationBias를 사용하여 특정 지역으로 검색 편향

includedPrimaryTypes 사용

요청 쿼리 예측

출처 사용

응답에서 거리가 누락됨

사용해 보기