모든 준비를 마쳤습니다!

개발을 시작하려면 개발자 문서로 이동하세요.

Google Places API Web Service 활성화

개발을 시작하기 위해 Google Developers Console에서 우선적으로 해야 할 일을 몇 가지 소개하겠습니다.

  1. 프로젝트 생성 또는 선택
  2. Google Places API Web Service 활성화
  3. 적합한 키 생성
계속

장소 자동완성

장소 자동완성 서비스는 HTTP 요청에 대한 응답으로 장소 예상 검색어를 반환하는 웹 서비스입니다. 이 요청은 텍스트 검색 문자열과 선택적인 지역 범위를 지정합니다. 이 서비스는 사업체, 주소 및 관심 지점과 같은 장소를 사용자 유형에 따라 반환하여, 텍스트 기반의 지역 검색 시에 자동완성 기능을 제공합니다.

장소 자동완성 요청

장소 자동완성 서비스는 Google Places API Web Service의 일부이며 API 키 및 할당량을 Google Places API Web Service와 공유합니다.

장소 자동완성 서비스는 단어 전체뿐만 아니라 하위 문자열로도 비교할 수 있습니다. 따라서 사용자가 입력하면 애플리케이션에서 쿼리를 전송하여 실시간으로 장소 예상 검색어를 제공할 수 있습니다.

반환된 예상 검색어는 사용자에게 표시되어 원하는 장소를 선택하는 데 도움을 줍니다. 장소 세부정보 요청을 전송하면 반환된 모든 장소에 관한 세부정보를 확인할 수 있습니다.

장소 자동완성 요청은 다음 형식을 사용하는 HTTP URL입니다.

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

여기서 output은 다음 값 중 하나입니다.

  • json(권장)은 출력을 JSON(JavaScript Object Notation) 형식으로 나타냅니다.
  • xml은 출력을 XML로 나타냅니다.

장소 자동완성 요청을 시작하기 위해서는 특정 매개변수가 필요합니다. URL 표준 형식과 마찬가지로, 모든 매개변수는 앰퍼샌드(&) 문자를 사용하여 구분합니다. 매개변수 및 가능한 값 목록은 아래와 같습니다.

필수 매개변수

  • input — 검색할 텍스트 문자열입니다. 장소 자동완성 서비스는 이 문자열을 기준으로 일치 가능성이 높은 항목을 반환하고, 감지된 관련성을 기준으로 검색 결과를 정렬합니다.
  • key — 애플리케이션의 API 키. 이 키는 할당량 관리를 위해 애플리케이션을 식별합니다. 자세한 내용은 키 가져오기를 참조하세요. Google Maps API Premium Plan 고객은 프리미엄 플랜 구매 시에 생성된 API 프로젝트를 사용해야 합니다.

선택적 매개변수

  • offset — 서비스가 입력한 검색어에서 예상 일치 항목을 찾는 데 사용하는 마지막 문자의 위치. 예를 들어, 입력한 검색어가 'Google'이고 offset이 3이면 서비스는 'Goo'에서 일치 항목을 찾습니다. offset이 지정된 문자열은 입력한 검색어의 첫 단어에 대해서만 일치 항목을 찾습니다. 예를 들어, 입력한 검색어가 'Google abc'이고 offset이 3이면 서비스가 'Goo abc'와 일치하는 항목을 찾습니다. offset이 지정되지 않은 경우 서비스는 단어 전체를 사용합니다. offset은 일반적으로 텍스트 캐럿의 위치로 설정되어야 합니다.
  • location — 장소 정보를 검색하려는 지점. 위도,경도로 지정해야 합니다.
  • radius — 미터 단위의 거리로, 이 안에서 장소 결과가 반환됩니다. radius를 설정하면 결과가 표시된 지역으로 편중되지만, 지정된 지역으로 완전히 제한되지 않을 수도 있습니다. 아래의 위치 편중위치 제한을 참조하세요.
  • language — 결과를 반환하는 데 사용되는 언어를 나타내는 언어 코드(가능한 경우). 검색은 또한 선택한 언어로도 편중되며, 선택한 언어로 된 결과에는 더 높은 순위가 부여될 수도 있습니다. 지원되는 언어 목록 및 관련 코드를 참조하세요. 지원되는 언어는 자주 업데이트되므로 목록이 완전하지 않을 수 있습니다. 언어를 지정하지 않으면, 장소 자동완성 서비스는 요청을 전송한 도메인의 기본 언어를 사용하려고 시도합니다.
  • types — 반환할 장소 결과의 유형. 아래의 장소 유형을 참조하세요. 유형을 지정하지 않으면 모든 유형이 반환됩니다.
  • components— 결과를 제한할 장소 그룹. 현재는 components를 사용하여 국가별로 필터링할 수 있습니다. 국가는 두 글자(ISO 3166-1 Alpha-2 호환 국가 코드)로 전달되어야 합니다. 예를 들어, components=country:fr은 프랑스 내 장소로 결과를 제한합니다.
  • strictboundslocationradius로 정의된 지역 내의 장소만 반환합니다. 이는 편중이 아니라 제한입니다. 즉, 이 지역을 벗어나는 결과는 사용자 입력과 일치하더라도 반환되지 않습니다.

위치 편중

locationradius 매개변수를 전달하여 지정한 원 내로 결과를 제한할 수 있습니다. 이렇게 하면 장소 자동완성 서비스에서 원 내의 결과를 우선적으로 표시하도록 지시합니다. 하지만 여전히 정의한 영역을 벗어난 결과가 표시될 수도 있습니다. components 매개변수를 사용하여 특정 국가 내의 장소만 표시되도록 결과를 필터링할 수 있습니다.

팁: 시설(establishment)에 대한 결과는 일반적으로 검색 영역이 광범위한 경우 결과에 표시될 만큼 순위가 높지 않습니다. 시설이 혼합 시설/지오코드 결과에 표시되게 하려면, 반경을 더 좁게 지정하면 됩니다. 또는 types=establishment를 사용하여 검색 결과를 시설로만 제한할 수 있습니다.

위치 제한

또한 strictbounds 매개변수를 추가하여 locationradius 매개변수로 정의된 지역으로만 결과를 제한할 수 있습니다. 이 경우 장소 자동완성 서비스는 해당 지역 내의 결과만을 반환합니다.

장소 유형

types 매개변수를 전달하여 장소 자동완성 요청의 결과를 특정 유형으로 제한할 수 있습니다. 이 매개변수는 아래의 지원 유형에 나오는 특정 유형이나 유형 집합을 지정합니다. 유형을 지정하지 않으면 모든 유형이 반환됩니다. 일반적으로 하나의 유형만 허용됩니다. 예외적으로 geocode 유형과 establishment 유형은 안전하게 혼용할 수 있지만, 유형을 지정하지 않은 경우와 효과는 동일합니다. 지원 유형은 다음과 같습니다.

  • geocode는 장소 자동완성 서비스에게 사업체 결과 대신 지오코딩 결과만 반환하도록 지시합니다. 일반적으로 지정된 위치가 명확하지 않은 경우 이 요청을 사용하여 결과를 명확히 도출할 수 있습니다.
  • address는 장소 자동완성 서비스에게 정확한 주소를 지닌 지오코딩 결과만 반환하도록 지시합니다. 일반적으로 사용자가 완전히 지정된 주소를 찾을 것이라는 사실을 알고 있는 경우 이 요청을 사용합니다.
  • establishment는 장소 자동완성 서비스에게 사업체 결과만 반환하도록 지시합니다.
  • (regions) 유형 집합은 장소 서비스에게 다음 유형과 일치하는 모든 결과를 반환하도록 지시합니다.
    • locality
    • sublocality
    • postal_code
    • country
    • administrative_area_level_1
    • administrative_area_level_2
  • (cities) 유형 집합은 장소 서비스에게 locality 또는 administrative_area_level_3와 일치하는 결과를 반환하도록 지시합니다.

예시 자동완성 요청

캘리포니아 샌프란시스코를 중심으로 한 영역 내에서 문자열 'Ameoba'가 포함된 시설 요청:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY

샌프란시스코 Ashbury 거리와 Haight 거리로부터 500미터 이내인 결과만을 반환하는 동일 요청:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&strictbounds&key=YOUR_API_KEY

문자열 'Vict'가 포함된 주소를 프랑스어 결과로 요청:

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

이 예시의 API 키는 본인의 키로 대체해야 합니다.

장소 자동완성 응답

장소 자동완성 응답은 요청된 URL 경로 내에 output 플래그에서 지정한 형식으로 반환됩니다. 아래 결과는 다음 매개변수가 포함된 쿼리에 대해 반환된 결과입니다.

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions" : [
      {
         "description" : "Paris, France",
         "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
         "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris"
            },
            {
               "offset" : 7,
               "value" : "France"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },
      {
         "description" : "Paris Avenue, Earlwood, New South Wales, Australia",
         "id" : "359a75f8beff14b1c94f3d42c2aabfac2afbabad",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJrU3KAHG6EmsR5Uwfrk7azrI",
         "reference" : "CkQ2AAAARbzLE-tsSQPgwv8JKBaVtbjY48kInQo9tny0k07FOYb3Z_z_yDTFhQB_Ehpu-IKhvj8Msdb1rJlX7xMr9kfOVRIQVuL4tOtx9L7U8pC0Zx5bLBoUTFbw9R2lTn_EuBayhDvugt8T0Oo",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Avenue"
            },
            {
               "offset" : 14,
               "value" : "Earlwood"
            },
            {
               "offset" : 24,
               "value" : "New South Wales"
            },
            {
               "offset" : 41,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
      {
         "description" : "Paris Street, Carlton, New South Wales, Australia",
         "id" : "bee539812eeda477dad282bcc8310758fb31d64d",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJCfeffMi5EmsRp7ykjcnb3VY",
         "reference" : "CkQ1AAAAAERlxMXkaNPLDxUJFLm4xkzX_h8I49HvGPvmtZjlYSVWp9yUhQSwfsdveHV0yhzYki3nguTBTVX2NzmJDukq9RIQNcoFTuz642b4LIzmLgcr5RoUrZhuNqnFHegHsAjtoUUjmhy4_rA",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Street"
            },
            {
               "offset" : 14,
               "value" : "Carlton"
            },
            {
               "offset" : 23,
               "value" : "New South Wales"
            },
            {
               "offset" : 40,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
  ...additional results ...
      
XML
<?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>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <reference>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</reference>
  <id>691b237b0322f28988f3ce03e321ff72a12167fd</id>
  <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>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJrU3KAHG6EmsR5Uwfrk7azrI</place_id>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJCfeffMi5EmsRp7ykjcnb3VY</place_id>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

JSON 응답은 다음 두 가지 루트 요소를 포함합니다.

  • "status"는 요청의 메타데이터를 포함합니다. 아래의 상태 코드를 참조하세요.
  • predictions는 장소에 대한 정보와 함께 장소 배열을 포함합니다. 이러한 결과에 대한 자세한 내용은 장소 자동완성 결과를 참조하세요. Google Places API Web Service는 최대 5개의 결과를 반환합니다.

결과 내에서 특히 관심을 끄는 항목은 place_id 요소이며, 이 요소를 사용하면 별도의 쿼리를 통해 장소에 대한 더 구체적인 정보를 요청할 수 있습니다. 장소 세부정보 요청을 참조하세요.

JSON 응답 분석에 대한 도움말은 Javascript로 JSON 처리를 참조하세요.

XML 응답은 다음과 같은 2개의 하위 요소 유형을 가진 단일 <AutocompletionResponse> 요소로 구성됩니다.

  • 단일 <status> 요소는 요청의 메타데이터를 포함합니다. 아래의 상태 코드를 참조하세요.
  • 0개 이상의 <prediction> 요소가 있으며, 각 요소는 단일 장소에 대한 정보를 포함합니다. 이러한 결과에 대한 자세한 내용은 장소 자동완성 결과를 참조하세요. Google Places API Web Service는 최대 5개의 결과를 반환합니다.

어떤 이유로 애플리케이션에 xml이 꼭 필요한 경우가 아니라면 json을 기본 출력 플래그로 사용하는 것이 좋습니다. XML 트리를 처리할 때는 올바른 노드와 요소를 참조하도록 주의해야 합니다. XML 처리에 대한 도움말은 XPath로 XML 구문 분석을 참조하세요.

상태 코드

장소 자동완성 응답 객체의 status 필드는 요청의 상태를 포함합니다. 또한 장소 자동완성 요청이 실패한 원인을 추적하는 데 도움이 되는 디버깅 정보를 포함할 수 있습니다. status 필드는 다음 값을 포함할 수 있습니다.

  • OK는 오류가 없으며 하나 이상의 결과가 반환되었음을 나타냅니다.
  • ZERO_RESULTS는 검색에 성공했지만 반환된 결과가 없음을 나타냅니다. 이는 멀리 떨어진 위치의 bounds가 검색에 전달된 경우 발생할 수 있습니다.
  • OVER_QUERY_LIMIT는 할당량이 초과되었음을 나타냅니다.
  • REQUEST_DENIED는 요청이 거부되었음을 나타냅니다. 일반적인 원인은 key 매개변수가 잘못되었기 때문입니다.
  • INVALID_REQUEST는 일반적으로 input 매개변수가 없음을 나타냅니다.

오류 메시지

장소 서비스가 OK 이외의 상태 코드를 반환하면 응답 객체에 추가 error_message 필드가 있을 수 있습니다. 이 필드에는 지정된 상태 코드가 제시된 이유에 대한 상세정보가 포함됩니다.

장소 자동완성 결과

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

각 예상 검색어 결과는 다음 필드를 포함합니다.

  • description은 사람이 읽을 수 있는 반환된 결과의 이름을 포함합니다. establishment 결과에서, 이 이름은 대개 사업체 이름입니다.
  • place_id는 장소를 고유하게 식별하는 텍스트 식별자입니다. 장소에 대한 정보를 검색하려면 이 식별자를 Google Places API Web Service 요청의 placeId 필드에 삽입해 전달합니다. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참조하세요.
  • reference장소 세부정보 요청에서 장소에 대한 추가적인 정보를 검색하는 데 사용할 수 있는 고유 토큰을 포함합니다. 토큰은 장소를 고유하게 식별하지만 장소는 토큰을 식별하지 못합니다. 한 장소에 다수의 유효한 참조 토큰이 있을 수 있습니다. 다른 검색에서 특정 장소에 대해 동일한 토큰이 반환되지 않을 수도 있습니다. 참고: reference는 이제 지원이 중단되고 place_id로 대체됩니다. 이 페이지의 사용 중단 알림을 참조하세요.
  • id는 이 장소를 표시하는 안정적인 고유 식별자를 포함합니다. 이 식별자는 이 장소에 대한 정보를 검색하는 데 사용할 수 없지만, 장소에 관한 데이터를 통합하고 별도의 검색을 통해 장소의 ID를 확인하는 데 사용할 수 있습니다. 참고: id는 이제 지원이 중단되고 place_id로 대체됩니다. 이 페이지의 지원 중단 고지를 참조하세요.
  • terms는 반환된 설명의 각 섹션(설명의 한 섹션은 일반적으로 쉼표로 끝남)을 식별하는 검색어의 배열을 포함합니다. 배열의 각 항목에는 검색어의 텍스트를 포함하는 value 필드와, 설명에서 이 검색어의 시작 지점을 정의하는 유니코드 문자로 측정된 offset 필드가 있습니다.
  • types는 장소에 적용되는 유형의 배열을 포함합니다. 예: [ "political", "locality" ] 또는 [ "establishment", "geocode" ].
  • matched_substringsoffset 값과 length가 있는 배열을 포함합니다. 이 필드는 예상 검색어 결과 텍스트에 입력된 검색어의 위치를 표시하므로, 원하는 경우 예상 검색어를 강조 표시할 수 있습니다.

sensor 매개변수

이전의 Google Places API Web Service는 사용자 위치 파악을 위해 애플리케이션의 센서 사용 여부를 표시하는 sensor 매개변수를 포함하도록 요구했습니다. 이 매개변수는 더 이상 필요하지 않습니다.

다음에 대한 의견 보내기...

location_on
Google Places API Web Service