Method: places.autocomplete

지정된 입력에 대한 예측을 반환합니다.

HTTP 요청

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

URL은 gRPC 트랜스코딩 구문을 사용합니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string,
  "includePureServiceAreaBusinesses": boolean,
  "includeFutureOpeningBusinesses": boolean
}
필드
input

string

필수 항목입니다. 검색할 텍스트 문자열입니다.
locationBias

object (LocationBias)

선택사항입니다. 지정된 위치에 편중된 결과

locationBias 또는 locationRestriction 중 하나만 설정해야 합니다. 둘 다 설정되지 않은 경우 결과는 IP 주소에 따라 편향됩니다. 즉, IP 주소가 부정확한 위치에 매핑되고 편향 신호로 사용됩니다.
locationRestriction

object (LocationRestriction)

선택사항입니다. 결과를 지정된 위치로 제한합니다.

locationBias 또는 locationRestriction 중 하나만 설정해야 합니다. 둘 다 설정되지 않은 경우 결과는 IP 주소에 따라 편향됩니다. 즉, IP 주소가 부정확한 위치에 매핑되고 편향 신호로 사용됩니다.
includedPrimaryTypes[]

string

선택사항입니다. 장소 유형 (https://developers.google.com/maps/documentation/places/web-service/place-types))에 포함된 기본 장소 유형 (예: 'restaurant' 또는 'gas_station') 또는 (regions)만 또는 (cities)만 기본 유형이 이 목록에 포함된 경우에만 장소가 반환됩니다. 최대 5개의 값을 지정할 수 있습니다. 유형을 지정하지 않으면 모든 장소 유형이 반환됩니다.
includedRegionCodes[]

string

선택사항입니다. 최대 15개의 CLDR 2자리 지역 코드로 지정된 지역의 결과만 포함합니다. 빈 집합은 결과를 제한하지 않습니다. locationRestriction와 includedRegionCodes가 모두 설정된 경우 결과는 교차 영역에 위치합니다.
languageCode

string

선택사항입니다. 결과를 반환할 언어입니다. 기본값은 en-US입니다. input에 사용된 언어가 languageCode와 다르거나 반환된 장소에 현지 언어에서 languageCode로의 번역이 없는 경우 결과가 혼합된 언어로 표시될 수 있습니다.
regionCode

string

선택사항입니다. 지역 코드입니다. CLDR 2자리 지역 코드로 지정됩니다. 이는 주소 형식, 결과 순위에 영향을 미치며 반환되는 결과에 영향을 줄 수 있습니다. 이렇게 해도 결과가 지정된 지역으로 제한되지는 않습니다. 결과를 리전으로 제한하려면 region_code_restriction을 사용합니다.
origin

object (LatLng)

선택사항입니다. 목적지까지의 측지 거리를 계산할 원점입니다 (distanceMeters로 반환됨). 이 값이 생략되면 측지 거리가 반환되지 않습니다.
inputOffset

integer

선택사항입니다. input의 커서 위치를 나타내는 0부터 시작하는 유니코드 문자 오프셋 input입니다. 커서 위치는 반환되는 예측에 영향을 줄 수 있습니다.

비어 있으면 기본값은 input의 길이입니다.
includeQueryPredictions

boolean

선택사항입니다. true인 경우 응답에 장소와 쿼리 예측이 모두 포함됩니다. 그렇지 않으면 응답에서 장소 예상 검색어만 반환합니다.
sessionToken

string

선택사항입니다. 청구 목적으로 자동 완성 세션을 식별하는 문자열입니다. 최대 길이가 36개의 ASCII 문자인 URL 및 파일 이름 안전 base64 문자열이어야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.

세션은 사용자가 쿼리를 입력하기 시작하면 시작되고 장소를 선택하고 Place Details 또는 Address Validation 호출이 이루어지면 종료됩니다. 세션마다 여러 개의 쿼리가 포함될 수 있으며 하나의 장소 세부정보 또는 주소 유효성 검사 요청이 이어집니다. 세션 내 각 요청에 사용되는 사용자 인증 정보는 동일한 Google Cloud 콘솔 프로젝트에 속해야 합니다. 세션이 종료되면 토큰이 더 이상 유효하지 않습니다. 앱에서 각 세션에 대해 새 토큰을 생성해야 합니다. sessionToken 매개변수가 생략되거나 세션 토큰을 재사용하는 경우 세션 토큰이 제공되지 않은 것처럼 세션에 대해 요금이 청구됩니다 (각 요청에 대해 별도로 요금이 청구됨).

다음 가이드라인이 권장됩니다.

  • 모든 Place Autocomplete 호출에 세션 토큰을 사용합니다.
  • 각 세션에 대해 새 토큰을 생성합니다. 버전 4 UUID를 사용하는 것이 좋습니다.
  • 세션 내의 모든 Place Autocomplete, Place Details, Address Validation 요청에 사용되는 사용자 인증 정보가 동일한 Cloud Console 프로젝트에 속하는지 확인합니다.
  • 새 세션마다 고유한 세션 토큰을 전달해야 합니다. 두 개 이상의 세션에 동일한 토큰을 사용하면 각 요청에 대해 개별적으로 요금이 청구됩니다.
includePureServiceAreaBusinesses

boolean

선택사항입니다. 필드가 true로 설정된 경우 순수 방문 서비스 업체를 포함합니다. 순수 방문 서비스 업체는 고객에게 방문 또는 배달 서비스를 제공하지만 비즈니스 주소지에서는 고객에게 서비스를 제공하지 않는 비즈니스입니다. 청소 서비스 또는 배관공 등의 비즈니스가 있습니다. 이러한 비즈니스에는 Google 지도에 실제 주소나 위치가 없습니다. 장소에서는 이러한 비즈니스에 대해 location, plusCode 및 기타 위치 관련 필드를 반환하지 않습니다.
includeFutureOpeningBusinesses

boolean

선택사항입니다. true인 경우 아직 개업하지 않았지만 향후 개업할 비즈니스를 포함합니다.

응답 본문

places.autocomplete의 응답 프로토콜입니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

JSON 표현 
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
필드
suggestions[]

object (Suggestion)

관련성의 내림차순으로 정렬된 추천 목록이 포함됩니다.

승인 범위

다음 OAuth 범위가 필요합니다.

  • https://www.googleapis.com/auth/cloud-platform

LocationBias

검색할 지역입니다. 결과가 지정된 지역을 중심으로 편향될 수 있습니다.

JSON 표현 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
필드

통합 필드 type.

type는 다음 중 하나여야 합니다.
rectangle

object (Viewport)

북동쪽 모서리와 남서쪽 모서리로 정의된 뷰포트입니다.
circle

object (Circle)

중심점과 반지름으로 정의된 원입니다.

LocationRestriction

검색할 지역입니다. 결과는 지정된 지역으로 제한됩니다.

JSON 표현 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
필드

통합 필드 type.

type는 다음 중 하나여야 합니다.
rectangle

object (Viewport)

북동쪽 모서리와 남서쪽 모서리로 정의된 뷰포트입니다.
circle

object (Circle)

중심점과 반지름으로 정의된 원입니다.

추천

자동 완성 추천 결과입니다.

JSON 표현 
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
필드

통합 필드 kind.

kind는 다음 중 하나여야 합니다.
placePrediction

object (PlacePrediction)

장소에 대한 예측입니다.
queryPrediction

object (QueryPrediction)

질문에 대한 예측입니다.

PlacePrediction

Place Autocomplete 예상 검색어의 예상 결과입니다.

JSON 표현 
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
필드
place

string

추천 장소의 리소스 이름입니다. 이 이름은 장소 이름을 허용하는 다른 API에서 사용할 수 있습니다.
placeId

string

추천 장소의 고유 식별자입니다. 이 식별자는 장소 ID를 허용하는 다른 API에서 사용할 수 있습니다.
text

object (FormattableText)

반환된 결과의 사람이 읽을 수 있는 이름을 포함합니다. 시설 결과의 경우 일반적으로 업체 이름과 주소입니다.

text는 단일 UI 요소를 표시하려는 개발자에게 권장됩니다. 별개이지만 관련이 있는 두 UI 요소를 표시하려는 개발자는 대신 structuredFormat를 사용하는 것이 좋습니다. 장소 예측을 나타내는 두 가지 방법입니다. 사용자는 structuredFormat를 text로 파싱하거나 그 반대로 파싱하려고 하면 안 됩니다.

이 텍스트는 places.get에서 반환된 displayName와 다를 수 있습니다.

요청 input 및 languageCode이 서로 다른 언어로 되어 있거나 장소에 현지 언어에서 languageCode으로의 번역이 없는 경우 혼합된 언어로 표시될 수 있습니다.
structuredFormat

object (StructuredFormat)

장소 예측을 장소 이름을 포함하는 기본 텍스트와 추가적인 명확성 기능 (예: 도시 또는 지역)을 포함하는 보조 텍스트로 분류합니다.

structuredFormat는 별개이지만 관련이 있는 두 UI 요소를 표시하려는 개발자에게 권장됩니다. 단일 UI 요소를 표시하려는 개발자는 text를 대신 사용하는 것이 좋습니다. 장소 예측을 나타내는 두 가지 방법입니다. 사용자는 structuredFormat를 text로 파싱하거나 그 반대로 파싱하려고 하면 안 됩니다.
types[]

string

https://developers.google.com/maps/documentation/places/web-service/place-types의 표 A 또는 표 B에 나오는 이 장소에 적용되는 유형 목록입니다.

유형은 장소의 분류입니다. 공유 유형이 있는 장소는 유사한 특징을 공유합니다.
distanceMeters

integer

origin가 지정된 경우 origin에서 측지선의 길이(미터)입니다. 경로와 같은 일부 예측은 이 필드를 채우지 않을 수 있습니다.

FormattableText

장소 또는 쿼리 예측을 나타내는 텍스트입니다. 텍스트는 그대로 사용하거나 서식을 지정하여 사용할 수 있습니다.

JSON 표현 
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
필드
text

string

그대로 사용하거나 matches로 형식을 지정할 수 있는 텍스트입니다.
matches[]

object (StringRange)

text에서 입력 요청이 일치하는 위치를 식별하는 문자열 범위 목록입니다. 범위를 사용하여 text의 특정 부분의 형식을 지정할 수 있습니다. 문자열 일치 외의 기준 (예: 맞춤법 수정 또는 음역)에 따라 일치가 결정된 경우 하위 문자열이 input과 정확히 일치하지 않을 수 있습니다.

이러한 값은 text의 유니코드 문자 오프셋입니다. 범위는 오프셋 값이 증가하는 순서로 정렬됩니다.

StringRange

주어진 텍스트 내의 하위 문자열을 식별합니다.

JSON 표현 
{
  "startOffset": integer,
  "endOffset": integer
}
필드
startOffset

integer

문자열의 첫 번째 유니코드 문자의 0 기반 오프셋입니다 (포함).
endOffset

integer

마지막 유니코드 문자의 0부터 시작하는 오프셋입니다 (제외).

StructuredFormat

장소 또는 쿼리 예측을 기본 텍스트와 보조 텍스트로 분류한 내용을 포함합니다.

장소 예측의 경우 기본 텍스트에 장소의 구체적인 이름이 포함됩니다. 질문 예측의 경우 기본 텍스트에 질문이 포함됩니다.

보조 텍스트에는 장소를 추가로 식별하거나 쿼리를 구체화하기 위한 추가적인 명확성 기능 (예: 도시 또는 지역)이 포함됩니다.

JSON 표현 
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
필드
mainText

object (FormattableText)

장소 또는 검색어의 이름을 나타냅니다.
secondaryText

object (FormattableText)

장소를 추가로 식별하거나 쿼리를 구체화하기 위한 추가적인 명확성 확보 기능 (예: 도시 또는 지역)을 나타냅니다.

QueryPrediction

Query Autocomplete 예측의 예측 결과입니다.

JSON 표현 
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
필드
text

object (FormattableText)

예측된 텍스트입니다. 이 텍스트는 장소를 나타내는 것이 아니라 검색 엔드포인트 (예: 텍스트 검색)에서 사용할 수 있는 텍스트 쿼리를 나타냅니다.

text는 단일 UI 요소를 표시하려는 개발자에게 권장됩니다. 별개이지만 관련이 있는 두 UI 요소를 표시하려는 개발자는 대신 structuredFormat를 사용하는 것이 좋습니다. 이는 쿼리 예측을 나타내는 두 가지 방법입니다. 사용자는 structuredFormat를 text로 파싱하거나 그 반대로 파싱해서는 안 됩니다.

요청 input과 languageCode이 서로 다른 언어로 되어 있거나 쿼리의 일부가 현지 언어에서 languageCode으로 번역되지 않은 경우 언어가 혼합될 수 있습니다.
structuredFormat

object (StructuredFormat)

질문을 포함하는 기본 텍스트와 추가적인 명확성 확보 기능 (예: 도시 또는 지역)을 포함하는 보조 텍스트로 질문 예측을 분류합니다.

structuredFormat는 서로 관련이 있지만 별도의 두 UI 요소를 표시하려는 개발자에게 권장됩니다. 단일 UI 요소를 표시하려는 개발자는 대신 text를 사용하는 것이 좋습니다. 이는 쿼리 예측을 나타내는 두 가지 방법입니다. 사용자는 structuredFormat를 text로 파싱하거나 그 반대로 파싱해서는 안 됩니다.