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
}
필드
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

선택사항입니다. 결제 목적으로 자동 완성 세션을 식별하는 문자열입니다. URL 및 파일 이름에 안전한 base64 문자열이어야 하며 길이는 최대 36자(영문 기준)여야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.

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

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

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

boolean

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

응답 본문

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

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

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

object (Suggestion)

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

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

쿼리 자동 완성 예상 검색어의 예측 결과입니다.

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로 파싱하거나 그 반대로 파싱하려고 해서는 안 됩니다.