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

자동 완성 (신규)

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

자동 완성 (신규) 서비스는 장소를 반환하는 웹 서비스입니다. HTTP 요청에 대한 응답으로 예측 및 쿼리 예측을 수행합니다. 요청에서 텍스트 지정 검색 문자열과 검색 영역을 제어하는 지리적 경계가 포함됩니다.

자동 완성 (신규) 서비스는 전체 단어를 검색하고 입력의 하위 문자열, 장소 이름, 주소 및 Plus Code를 사용합니다. 따라서 애플리케이션은 즉시 장소 및 예상 검색어를 제공합니다.

Autocomplete (New) API의 응답에는 두 가지 유형이 포함될 수 있습니다. 예측:

장소 예상 검색어: 업체, 주소, 업체와 같은 장소 관심 분야로 이루어져 있습니다. 장소 예상 검색어 기본적으로 반환됩니다.
검색어 예상 검색어: 입력 텍스트 문자열 및 검색 영역 쿼리 예측은 기본적으로 반환되지 않습니다. 사용 쿼리 예측을 추가하는 includeQueryPredictions 요청 매개변수 있습니다.

예를 들어 부분 사용자 입력이 포함된 문자열을 입력으로 사용하여 API를 호출합니다. 'Sicilian piz'(캘리포니아주 샌프란시스코로 제한) 응답에는 문자열 및 검색 영역과 일치하는 장소 예상 검색어 목록(예: 'Sicilian Pizza Kitchen'이라는 이름의 식당을 소개하고 장소에 대한 세부정보와 함께 제공합니다.

반환된 장소 예상 검색어는 선택할 수 있습니다. 다음과 같은 방법을 사용할 수 있습니다. Place Details (신규) 반환된 장소 예상 검색어에 대한 자세한 정보를 가져옵니다.

응답에는 쿼리 예측 목록도 포함할 수 있으며 '시칠리아 피자' 또는 '시칠리아 피자' 등의 파스타'. 표에 포함된 각 쿼리 예측 권장 텍스트 검색 문자열이 있는 text 필드가 포함됩니다. 사용해 보기 문자열을 텍스트 검색 (신규) 더 자세한 검색을 수행할 수 있습니다.

API 탐색기를 사용하면 실시간 요청을 하여 API 및 API 옵션:

실습

자동 완성 (신규) 요청

자동 완성 (신규) 요청은 양식:

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

답변 정보

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

suggestions 배열에는 모든 예상 장소와 검색어가 순서대로 포함됩니다. 관련성에 따라 광고가 게재됩니다. 각 장소는 placePrediction 필드이며 각 쿼리는 queryPrediction 필드로 전달됩니다.
placePrediction 필드에는 단일 항목에 관한 자세한 정보가 포함됩니다. 장소 예상 검색어(장소 ID, 텍스트 설명 포함)를 제공합니다.
queryPrediction 필드에는 단일 항목에 관한 자세한 정보가 포함됩니다. 검색어 예측을 제공합니다.

를 통해 개인정보처리방침을 정의할 수 있습니다.

참고: 자동 완성 (신규)은 총 5개의 예상 검색어를 placePredictions 요청에 따라 queryPredictions 또는 둘의 조합으로 설정됩니다. 예를 들어 요청이 includeQueryPredictions를 설정하지 않은 경우 응답 본문에 최대 5개의 placePredictions입니다. 요청이 includeQueryPredictions를 설정하면 응답 본문에 placePredictions 조합으로 최대 5개의 예측 포함 및 queryPredictions

전체 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
            }]
        },
        ...
    }
  ...]
}

필수 매개변수

입력

검색할 텍스트 문자열입니다. 전체 단어 및 하위 문자열 지정 장소 이름, 주소 및 플러스 코드가 포함됩니다. 자동 완성 (신규) 서비스 는 이 문자열을 기준으로 일치 후보를 반환하고 관련성이 있습니다.

선택적 매개변수

includedPrimaryTypes

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

기본적으로 API는 input 매개변수를 기준으로 모든 장소를 반환합니다. 기본 유형 값의 값입니다. 결과를 특정 includedPrimaryTypes 매개변수를 전달하여 기본 유형 또는 기본 유형을 전달합니다.

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

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

다음과 같은 경우 INVALID_REQUEST 오류와 함께 요청이 거부됩니다.
- 5개 이상의 유형이 지정되었습니다.
- 모든 유형은 (cities) 또는 (regions) 외에 추가로 지정됩니다.
- 인식할 수 없는 유형이 모두 지정되었습니다.
를 통해 개인정보처리방침을 정의할 수 있습니다.
참고: includedPrimaryTypes 매개변수는 장소의 기본 유형에서만 작동합니다. 장소와 관련된 모든 유형이 아닙니다. 모든 장소에 기본 유형이 있지만 기본 유형은 Places API (신규)에서 지원됩니다. 지원되는 유형에는 표 A 또는 표 B.
includeQueryPredictions

true이면 응답에 장소 및 예상 검색어가 모두 포함됩니다. 기본값 값이 false입니다. 즉, 응답에 장소 예상 검색어만 포함됩니다.
includedRegionCodes

최대 15개의 배열로 지정된 지정된 지역 목록의 결과만 포함합니다. ccTLD('최상위 도메인') 2자(영문 기준) 값이어야 합니다. 생략할 경우 응답에 제한이 적용되지 않습니다. 예를 들어 독일과 프랑스로 지역을 제한하세요.
```
    "includedRegionCodes": ["de", "fr"]
```
locationRestriction와 includedRegionCodes를 모두 지정하는 경우 두 설정이 교차하는 영역에 검색 결과가 표시됩니다.
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이면 API가 기본적으로 IP 바이어스를 사용합니다. IP 편중을 사용하면 API는 기기의 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
  }
}
```
- 직사각형은 위도-경도 표시 영역으로, 2로 표현됩니다. 대각선 반대쪽에 있는 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
    }
  }
}
```
출처

지점까지의 직선 거리를 계산할 출발지입니다. 대상 (distanceMeters로 반환됨) 이 값이 생략하면 직선 거리는 반환되지 않습니다. 다음과 같이 지정해야 합니다. 위도 및 경도 좌표:
```
"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}
```
regionCode

응답 형식을 지정하는 데 사용되는 지역 코드로, ccTLD('최상위 도메인') 2자리 문자 값입니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하지만 몇 가지 주목할 만한 예외가 있습니다 예를 들어 영국의 ccTLD는 'uk' (.co.uk), ISO 3166-1 코드는 'gb'입니다. (기술적으로 '영국 및 북아일랜드'의 법인 소유입니다.

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

세션 토큰은 자동 완성을 추적하는 사용자 생성 문자열입니다. (신규) 통화를 '세션'으로 집계 자동 완성 (신규)은 세션 토큰을 사용하여 사용자 자동완성 검색의 쿼리 및 선택 단계를 개별 세션으로 그룹화하여 있습니다. 자세한 내용은 세션 토큰.

자동 완성 (신규) 예시

locationRestriction 및 locationBias 사용

API는 기본적으로 IP 상세 검색을 사용하여 검색 영역을 제어합니다. IP 바이어스의 경우 API는 결과를 상세 검색할 수 있도록 기기의 IP 주소입니다. 원하는 경우 locationRestriction 또는 locationBias 중 하나로 검색할 영역을 지정할 수 없습니다.

locationRestriction는 검색할 영역을 지정합니다. 지정된 영역을 벗어난 결과 반환되지 않습니다. 다음 예에서는 locationRestriction를 사용하여 샌프란시스코를 중심으로 한 반경 5000미터의 원에 요청을 보냅니다.

curl -X POST -d '{
  "input": "Amoeba",
  "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/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",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

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

이제 결과에 5000미터 반경을 벗어난 결과를 포함하여 더 많은 항목이 포함됩니다.

{
  "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"
        ]
      }
    },
    ...
  ]
}

includePrimaryTypes 사용

includedPrimaryTypes 매개변수를 사용하여 표 A 표 B, (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을 포함하면 API는 distanceMeters 필드를 origin에서 목적지까지의 직선 거리가 포함된 응답입니다. 다음 예는 원점을 샌프란시스코의 중심으로 설정합니다.

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
      }
    }
  ]
}

사용해 보기

API 탐색기를 사용하면 샘플 요청을 수행하여 API 및 API 옵션에 익숙해지실 수 있습니다.

API 아이콘 을 선택합니다. 을 클릭합니다.
필요한 경우 표준 매개변수 표시를 펼치고 fields 매개변수 필드 마스크에 추가합니다.
필요한 경우 요청 본문을 수정합니다.
실행 버튼을 선택합니다. 팝업에서 요청에 사용할 계정을 선택합니다.
API 탐색기 패널에서 펼치기 아이콘을 선택합니다. : API 탐색기 창을 펼칩니다.

자동 완성 (신규)

자동 완성 (신규) 요청

답변 정보

필수 매개변수

입력

선택적 매개변수

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias 또는 locationRestriction

locationBias

locationRestriction

출처

regionCode

sessionToken

자동 완성 (신규) 예시

locationRestriction 및 locationBias 사용

includePrimaryTypes 사용

쿼리 예측 요청

출처 사용

사용해 보기