Place Autocomplete (기존)

Place Autocomplete (레거시)은 HTTP 요청에 대한 응답으로 장소 예상 검색어를 반환하는 웹 서비스입니다. 요청은 텍스트 검색 문자열과 선택적 지리적 경계를 지정합니다. 이 서비스는 사용자가 입력할 때 비즈니스, 주소, 관심 장소와 같은 장소를 반환하여 텍스트 기반 지리 검색에 자동 완성 기능을 제공하는 데 사용할 수 있습니다.

Place Autocomplete (기존) 요청

Place Autocomplete (레거시)은 Places API의 일부이며 Places API와 API 키 및 할당량을 공유합니다.

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

플러스 코드는 올바르게 형식을 지정해야 합니다. 즉, 더하기 기호를 %2B로 URL 이스케이프 처리하고 공백을 %20로 URL 이스케이프 처리해야 합니다.

• 글로벌 코드는 4자리 지역 코드와 6자 이상의 로컬 코드입니다. 예를 들어 URL 이스케이프 전역 코드 849VCWC8+R9는 849VCWC8%2BR9입니다.
• 복합 코드는 명시적인 위치가 포함된 6자 이상의 로컬 코드입니다. 예를 들어 URL 이스케이프된 복합 코드 CWC8+R9 Mountain View, CA, USA는 CWC8%2BR9%20Mountain%20View%20CA%20USA입니다.

반환된 예측은 사용자가 원하는 장소를 선택하는 데 도움이 되도록 사용자에게 표시되도록 설계되었습니다. 반환된 장소에 대한 자세한 내용을 확인하려면 장소 세부정보 (기존) 요청을 전송하세요.

Place Autocomplete (레거시) 요청은 다음 형식의 HTTP URL입니다.

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

여기서 output은 다음 값 중 하나일 수 있습니다.

• json (권장)은 JavaScript 객체 표기법 (JSON)으로 출력을 나타냅니다.
• xml는 XML로 출력을 나타냅니다.

Place Autocomplete (기존) 요청을 시작하려면 특정 매개변수가 필요합니다. URL에서와 마찬가지로 모든 매개변수는 앰퍼샌드(&) 문자를 사용하여 구분합니다. 매개변수 목록과 가능한 값은 아래에 열거되어 있습니다.

필수 매개변수

• 입력

  검색할 텍스트 문자열입니다. Place Autocomplete 서비스는 이 문자열을 기반으로 일치 가능성이 있는 항목을 반환하고 감지된 관련성을 기반으로 검색 결과를 정렬합니다.

선택적 매개변수

• components

  검색 결과를 제한하려는 장소의 그룹입니다. 구성요소를 사용하여 최대 5개 국가로 필터링할 수 있습니다. 국가는 2자리 ISO 3166-1 Alpha-2 호환 국가 코드로 전달해야 합니다. 예를 들어 components=country:fr를 사용하면 검색 결과가 프랑스 내 장소로 제한됩니다. 여러 국가는 파이프 문자 |를 구분자로 사용하여 여러 country:XX 필터로 전달해야 합니다. 예를 들어 components=country:us|country:pr|country:vi|country:gu|country:mp 를 사용하면 미국 및 미편입 조직화된 지역 내의 장소로 검색 결과가 제한됩니다.

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

• language

  결과를 반환할 언어입니다.

  • 지원되는 언어 목록을 참고하세요. Google에서는 지원되는 언어를 자주 업데이트하므로 이 목록에 모든 언어가 포함되지 않을 수도 있습니다.
  • language가 제공되지 않으면 API는 Accept-Language 헤더에 지정된 기본 언어를 사용하려고 시도합니다.
  • API는 사용자와 현지인 모두가 읽을 수 있는 상세 주소를 제공하기 위해 최선을 다합니다. 이 목표를 달성하기 위해 선호하는 언어를 준수하여 필요한 경우 사용자가 읽을 수 있는 스크립트로 음역된 현지 언어의 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
  • 선호하는 언어로 이름을 사용할 수 없는 경우 API는 가장 일치하는 이름을 사용합니다.
  • 기본 언어는 API가 반환하도록 선택한 결과 집합과 반환되는 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 약어를 다르게 해석합니다. 예를 들어 거리 유형의 약어나 한 언어에서는 유효하지만 다른 언어에서는 유효하지 않은 동의어가 있습니다. 예를 들어 utca와 tér은 헝가리어로 거리의 동의어입니다.

• 위치

  장소 정보를 가져올 중심점입니다. latitude,longitude로 지정해야 합니다. 위치를 지정할 때는 radius 매개변수도 제공해야 합니다. radius가 제공되지 않으면 location 매개변수가 무시됩니다.

  Text Search API를 사용할 때 `query` 에 `Barcelona의 시장` 과 같은 명시적 위치가 포함된 경우 `location` 매개변수가 재정의될 수 있습니다.

• locationbias

  반경과 위도/경도를 지정하거나 직사각형의 점을 나타내는 두 개의 위도/경도 쌍을 지정하여 지정된 지역의 결과를 우선합니다. 이 매개변수를 지정하지 않으면 API에서 기본적으로 IP 주소 바이어스를 사용합니다.

  • IP 편향: API에 IP 주소 편향을 사용하도록 지시합니다. ipbias 문자열을 전달합니다 (이 옵션에는 추가 매개변수가 없음).
  • 원형: 반지름(미터)과 위도/경도(십진수)를 지정하는 문자열입니다. circle:radius@lat,lng 형식을 사용하세요.
  • 직사각형: 직사각형의 남서쪽 및 북동쪽 지점을 나타내는 2개의 위도/경도 쌍을 십진수로 지정하는 문자열입니다. rectangle:south,west|north,east 형식을 사용합니다. 동/서 값은 -180~180 범위로 래핑되고 북/남 값은 -90~90 범위로 클램핑됩니다.

• locationrestriction

  반경과 위도/경도를 지정하거나 직사각형의 점을 나타내는 두 개의 위도/경도 쌍을 지정하여 결과를 지정된 영역으로 제한합니다.

  • 원형: 반지름(미터)과 위도/경도(십진수)를 지정하는 문자열입니다. circle:radius@lat,lng 형식을 사용하세요.
  • 직사각형: 직사각형의 남서쪽 및 북동쪽 지점을 나타내는 2개의 위도/경도 쌍을 십진수로 지정하는 문자열입니다. rectangle:south,west|north,east 형식을 사용합니다. 동/서 값은 -180~180 범위로 래핑되고 북/남 값은 -90~90 범위로 클램핑됩니다.

• 오프셋

  서비스가 예측을 일치시키는 데 사용하는 마지막 문자의 입력 용어 내 위치입니다. 예를 들어 입력이 Google이고 오프셋이 3이면 서비스는 Goo와 일치합니다. 오프셋으로 결정된 문자열은 입력된 용어의 첫 번째 단어와만 일치합니다. 예를 들어 입력된 용어가 Google abc이고 오프셋이 3이면 서비스는 Goo abc와 일치시키려고 시도합니다. 오프셋이 제공되지 않으면 서비스에서 전체 기간을 사용합니다. 오프셋은 일반적으로 텍스트 캐럿의 위치로 설정해야 합니다.

• origin

  대상까지의 직선 거리를 계산할 원점입니다 (distance_meters로 반환됨). 이 값을 생략하면 직선 거리가 반환되지 않습니다. latitude,longitude로 지정해야 합니다.

• 반경

  장소 결과를 반환할 거리 (미터)를 정의합니다. location 및 radius 매개변수를 전달하여 특정 원에 편중된 결과를 얻을 수 있습니다. 이렇게 하면 장소 서비스에서 해당 원 내의 결과를 우선적으로 표시합니다. 정의된 영역 밖의 결과가 표시될 수도 있습니다.

  반지름은 검색 유형 및 기타 매개변수에 따라 최대값으로 자동 제한됩니다.

  • 자동 완성: 50,000미터
  • 주변 검색:
    • keyword 또는 name 사용: 50,000미터
    • keyword 또는 name 없이
      • 최대 50,000미터이며, rankby 매개변수와 관계없이 지역 밀도에 따라 동적으로 조정됩니다.
      • rankby=distance를 사용하면 반경 매개변수가 허용되지 않으며 INVALID_REQUEST이 발생합니다.
  • Query Autocomplete: 50,000미터
  • 텍스트 검색: 50,000미터

• 지역

  ccTLD ('최상위 도메인') 2자리 값으로 지정되는 지역 코드입니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)이지만 ISO 3166-1 코드는 'gb' (기술적으로 '영국' 법인의 경우)입니다.

• sessiontoken

  결제 목적으로 자동 완성 세션을 식별하는 임의의 문자열입니다.

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

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

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

• strictbounds

  location 및 radius로 정의된 지역 내에 있는 장소만 반환합니다. 이는 편향이 아닌 제한사항입니다. 즉, 결과가 사용자 입력과 일치하더라도 이 지역 외부의 결과는 반환되지 않습니다.

• 유형

  types 매개변수를 전달하여 Place Autocomplete 요청의 결과를 특정 유형으로 제한할 수 있습니다. 이 매개변수는 장소 유형에 나열된 유형 또는 유형 모음을 지정합니다. 유형을 지정하지 않으면 모든 유형이 반환됩니다.

  장소에는 표 1 또는 표 2에 나열된 유형 중 단일 기본 유형만 있을 수 있습니다. 예를 들어 음식이 제공되는 호텔은 types=restaurant이 아닌 types=lodging만 반환될 수 있습니다.

  types 매개변수의 값으로 다음 중 하나를 지정할 수 있습니다.

  • 표 1 또는 표 2의 최대 5개 값 값이 여러 개인 경우 각 값을 | (세로 막대)로 구분합니다. 예를 들면 다음과 같습니다.

    types=book_store|cafe

  • 표 3에 있는 지원되는 단일 필터. 유형 컬렉션을 혼합할 수 없습니다.

  다음과 같은 경우 요청이 INVALID_REQUEST 오류로 거부됩니다.

  • 6개 이상의 유형이 지정되었습니다.
  • 인식할 수 없는 유형이 있습니다.
  • 표 1 또는 표 2의 유형이 표 3의 필터와 혼합되는 경우

Place Autocomplete (기존) 예

캘리포니아주 샌프란시스코를 중심으로 하는 지역 내에 'Amoeba' 문자열이 포함된 시설에 대한 요청:

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

샌프란시스코 애쉬베리 스트리트와 하이트 스트리트에서 500미터 이내의 결과로 제한된 동일한 요청:

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

프랑스어 검색결과에서 'Vict'가 포함된 주소 요청:

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=geocode
      &language=fr
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

'Vict'가 포함된 도시를 요청하고 브라질 포르투갈어로 결과를 표시합니다.

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=(cities)
      &language=pt_BR&key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

이 예의 API 키를 자체 키로 바꿔야 합니다.

Place Autocomplete (기존) 응답

장소 자동 완성 (기존) 응답은 요청의 URL 경로 내에 있는 output 플래그로 표시된 형식으로 반환됩니다. 아래 결과는 다음 매개변수가 포함된 쿼리에 대해 반환될 수 있는 결과를 나타냅니다.

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Paris
      &types=geocode
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

    
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

   

PlacesAutocompleteResponse

결과에서 특히 관심이 가는 부분은 place_id 요소입니다. 이 요소를 사용하면 별도의 쿼리를 사용하여 장소에 관한 더 구체적인 세부정보를 요청할 수 있습니다. 장소 세부정보 (기존) 요청을 참고하세요.

XML 응답은 두 가지 유형의 하위 요소가 있는 단일 <AutocompletionResponse> 요소로 구성됩니다.

• 단일 <status> 요소에는 요청에 관한 메타데이터가 포함됩니다. 아래의 상태 코드를 참고하세요.
• 0개 이상의 <prediction> 요소(각각 단일 장소에 관한 정보를 포함) 이러한 결과에 관한 자세한 내용은 장소 자동 완성 (레거시) 결과를 참고하세요. Places API는 최대 5개의 결과를 반환합니다.

애플리케이션에 어떤 이유로든 xml가 필요한 경우가 아니라면 json를 기본 출력 플래그로 사용하는 것이 좋습니다. XML 트리를 처리하려면 적절한 노드와 요소를 참조할 수 있도록 주의해야 합니다. XML 처리에 관한 도움말은 XPath로 XML 처리하기를 참고하세요.

PlacesAutocompleteStatus

서비스에서 반환된 상태 코드입니다.

• OK - API 요청이 성공적이었음을 나타냅니다.
• ZERO_RESULTS: 검색이 성공했지만 반환된 결과가 없습니다. 검색에 원격 위치의 경계가 전달된 경우 이 문제가 발생할 수 있습니다.
• INVALID_REQUEST - API 요청이 잘못되었음을 나타냅니다. 일반적으로 input 매개변수가 누락되었기 때문입니다.
• OVER_QUERY_LIMIT: 다음 중 하나를 나타냅니다.
  • QPS 한도를 초과했습니다.
  • 계정에 결제가 사용 설정되어 있지 않습니다.
  • 월 $200 크레딧 또는 자체 설정 사용량 한도를 초과했습니다.
  • 제공된 결제 수단이 더 이상 유효하지 않습니다 (예: 신용카드가 만료됨).
  이 오류를 해결하는 방법에 대한 자세한 내용은 지도 FAQ를 참고하세요.
• REQUEST_DENIED - 요청이 거부되었음을 나타냅니다. 일반적으로 다음과 같은 이유 때문입니다.
  • 요청에 API 키가 누락되었습니다.
  • key 매개변수가 잘못되었습니다.
• UNKNOWN_ERROR - 알 수 없는 오류를 나타냅니다.

장소 서비스가 검색에서 JSON 결과를 반환하면 predictions 배열 내에 배치합니다. 서비스가 결과를 반환하지 않더라도 (예: location이 원격인 경우) 빈 predictions 배열을 반환합니다. XML 응답은 0개 이상의 <prediction> 요소로 구성됩니다.

PlaceAutocompletePrediction

PlaceAutocompleteMatchedSubstring

PlaceAutocompleteStructuredFormat

PlaceAutocompleteTerm

Place Autocomplete (기존) 최적화

이 섹션에서는 Place Autocomplete (Legacy) 서비스를 최대한 활용하는 데 도움이 되는 권장사항을 설명합니다.

다음은 일반 가이드라인입니다.

• 작동하는 사용자 인터페이스를 개발하는 가장 빠른 방법은 Maps JavaScript API 장소 자동 완성 (기존) 위젯, Android용 Places SDK 장소 자동 완성 (기존) 위젯, iOS용 Places SDK 장소 자동 완성 (기존) UI 컨트롤을 사용하는 것입니다.
• 처음부터 필수 Place Autocomplete (이전) 데이터 필드를 이해합니다.
• 위치 상세 검색 및 위치 제한 필드는 선택사항이지만 자동 완성 성능에 상당한 영향을 미칠 수 있습니다.
• API가 오류를 반환하는 경우 오류 처리를 사용하여 앱의 성능이 적절히 저하되도록 합니다.
• 선택된 항목이 없을 때 앱에서 처리하고 사용자에게 계속할 수 있는 방법을 제공하도록 합니다.

비용 최적화 권장사항

기본 비용 최적화

Place Autocomplete (레거시) 서비스 사용 비용을 최적화하려면 Place Details (레거시) 및 Place Autocomplete (레거시) 위젯에서 필드 마스크를 사용하여 필요한 Place Autocomplete (레거시) 데이터 필드만 반환하세요.

고급 비용 최적화

SKU: Autocomplete - Per Request 가격에 액세스하고 Place Details (Legacy) 대신 선택된 장소에 대한 Geocoding API 결과를 요청하려면 Place Autocomplete (Legacy)를 프로그래매틱 방식으로 구현해 보세요. Geocoding API와 연결된 요청당 가격은 다음 두 조건이 모두 충족되는 경우 세션당 (세션 기반) 가격보다 비용 효과적입니다.

• 사용자가 선택한 장소의 위도/경도 또는 주소만 필요한 경우 Geocoding API는 장소 세부정보 (기존) 호출보다 낮은 비용으로 이 정보를 제공합니다.
• 사용자가 평균 네 개 이하의 Place Autocomplete (기존) 예상 검색어 요청 내에서 자동 완성 예상 검색어를 선택하면 요청당 가격이 세션당 가격보다 비용 효과적일 수 있습니다.

애플리케이션에 선택된 예상 검색어의 주소 및 위도/경도 이외의 정보가 필요한가요?

성능 권장사항

다음 가이드라인에서는 Place Autocomplete (기존) 성능을 최적화하는 방법을 설명합니다.

• Place Autocomplete (Legacy) 구현에 국가별 제한사항, 위치 상세 검색, (프로그래매틱 구현의 경우) 언어 환경설정을 추가합니다. 위젯은 사용자의 브라우저 또는 휴대기기에서 언어 환경설정을 선택하므로 언어 환경설정이 필요하지 않습니다.
• Place Autocomplete (기존)에 지도와 함께 제공된 경우 지도 표시 영역별로 위치를 상세 검색할 수 있습니다.
• 예상 검색어 중 원하는 결과 주소가 없어 사용자가 Place Autocomplete (Legacy) 예상 검색어 중 하나를 선택하지 않는 경우 원래 사용자 입력을 재사용하여 더 관련성 높은 결과를 얻을 수 있습니다.
  • 사용자가 주소 정보만 입력할 것으로 예상되는 경우 Geocoding API 호출 시 원래 사용자 입력을 재사용합니다.
  • 사용자가 이름 또는 주소로 특정 장소에 대한 쿼리를 입력할 것으로 예상되는 경우 Place Details (Legacy) 요청을 사용합니다. 특정 지역에서만 결과가 예상되는 경우 위치 상세 검색을 사용합니다.
  다음과 같은 경우에는 Geocoding API로 대체하는 것이 가장 좋습니다.
  • 건물 내 특정 단위 또는 아파트 주소와 같은 하위 건물 주소를 입력하는 사용자 예를 들어 체코 주소인 'Stroupežnického 3191/17, Praha'를 바탕으로 Place Autocomplete (기존)에서 부분 예측이 이루어집니다.
  • 사용자가 뉴욕시의 '23-30 29th St, Queens' 또는 하와이 카우아이섬의 '47-380 Kamehameha Hwy, Kaneohe'처럼 도로 구간 접두사가 있는 주소를 입력하는 경우

위치 편향

location 매개변수와 radius 매개변수를 전달하여 지정된 지역에 편중된 결과를 얻을 수 있습니다. 이렇게 하면 Place Autocomplete (기존)에서 정의된 영역 내 결과를 표시하도록 선호합니다. 정의된 영역 밖의 결과가 표시될 수도 있습니다. includedRegionCodes 매개변수를 사용하여 결과를 필터링하여 지정된 국가 내의 장소만 표시할 수 있습니다.

위치 제한

locationRestriction 매개변수를 전달하여 결과를 지정된 영역으로 제한합니다.

location 및 radius 매개변수로 정의된 지역으로 결과를 제한하려면 strictbounds 매개변수를 추가하세요. 이렇게 하면 Place Autocomplete (기존)가 해당 지역 내의 결과만 반환하도록 지시합니다.