모든 준비를 마쳤습니다!

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

Google Places API Web Service 활성화

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

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

쿼리 자동완성

쿼리 자동완성 서비스는 입력 시 추천 쿼리를 반환하여, 텍스트 기반 지역 검색을 위한 쿼리 예측을 제공하는 데 사용할 수 있습니다.

쿼리 자동완성 요청

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

쿼리 자동완성 서비스를 사용하면 실시간 지역 쿼리 예상 검색어를 애플리케이션에 추가할 수 있습니다. 특정 위치를 검색하는 대신 사용자는 '뉴욕시 부근의 피자 가게'와 같이 범주 검색어를 입력할 수 있습니다. 그러면 서비스에서 문자열과 일치하는 추천 쿼리 목록을 표시합니다. 쿼리 자동완성 서비스는 단어 전체는 물론 하위 문자열도 비교할 수 있습니다. 따라서 사용자가 입력하는 동안 애플리케이션에서 쿼리를 전송하여 실시간으로 장소 예상 검색어를 제공할 수 있습니다.

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

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

여기서 output 형식은 json 또는 xml 중 하나입니다.

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

필수 매개변수

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

선택적 매개변수

  • offset — 서비스가 입력한 검색어에서 예상 일치 항목을 찾는 데 사용하는 문자 위치. 예를 들어, 입력한 검색어가 'Googl'이고 완성 지점이 3이면 서비스는 'Goo'에서 일치 항목을 찾습니다. offset은 일반적으로 텍스트 캐럿의 위치로 설정되어야 합니다. 오프셋이 지정되지 않은 경우 서비스는 단어 전체를 사용합니다.
  • location — 장소 정보를 검색하려는 지점. 위도,경도로 지정해야 합니다.
  • radius — 미터 단위의 거리로, 이 안에서 장소 결과가 반환됩니다. radius를 설정하면 결과가 표시된 지역으로 제한되지만, 지정된 지역으로 완전히 제한되지 않을 수도 있습니다. 자세한 내용은 위치 편중을 참조하세요.
  • language — 결과를 반환하는 데 사용되는 언어를 나타내는 언어 코드(가능한 경우). 검색은 또한 선택한 언어로도 편중되며, 선택한 언어로 된 결과에는 더 높은 순위가 부여될 수도 있습니다. 지원되는 도메인 언어 목록을 참조하세요. 언어를 지정하지 않으면 장소 서비스가 요청을 전송한 도메인의 기본 언어를 사용하려고 시도합니다.

위치 편중

locationradius 매개변수를 전달하여 지정한 원 내로 결과를 제한할 수 있습니다. 이렇게 하면 장소 서비스에서 원 반경 내의 결과를 우선적으로 표시하도록 지시합니다. 하지만 여전히 정의한 영역을 벗어난 결과가 표시될 수도 있습니다.

예시 쿼리 자동완성 요청

"Pizza near Par" 요청:

https://maps.googleapis.com/maps/api/place/queryautocomplete/json?key=YOUR_API_KEY&input=pizza+near%20par

"Pizza near Par" 요청, 프랑스어 결과:

  https://maps.googleapis.com/maps/api/place/queryautocomplete/json?key=YOUR_API_KEY&language=fr&input=pizza+near%20par

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

쿼리 자동완성 응답

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

https://maps.googleapis.com/maps/api/place/queryautocomplete/xml?&key=YOUR_API_KEY&input=pizza+near+sydne

JSON
{
   "predictions" : [
      {
         "description" : "pizza near Sydney, New South Wales, Australia",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            },
            {
               "length" : 4,
               "offset" : 6
            },
            {
               "length" : 5,
               "offset" : 11
            }
         ],
         "terms" : [
            {
               "offset" : 0,
               "value" : "pizza"
            },
            {
               "offset" : 6,
               "value" : "near"
            },
            {
               "offset" : 11,
               "value" : "Sydney"
            },
            {
               "offset" : 19,
               "value" : "New South Wales"
            },
            {
               "offset" : 36,
               "value" : "Australia"
            }
         ]
      },
      {
         "description" : "pizza near Sydney, NS, Canada",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            },
            {
               "length" : 4,
               "offset" : 6
            },
            {
               "length" : 5,
               "offset" : 11
            }
         ],
         "terms" : [
            {
               "offset" : 0,
               "value" : "pizza"
            },
            {
               "offset" : 6,
               "value" : "near"
            },
            {
               "offset" : 11,
               "value" : "Sydney"
            },
            {
               "offset" : 19,
               "value" : "NS"
            },
            {
               "offset" : 23,
               "value" : "Canada"
            }
         ]
      },
        ...additional results ...
      {
         "description" : "Bondi Pizza, Campbell Parade, Sydney, New South Wales, Australia",
         "id" : "c478ed4e7cb075b307fdce4ad4f6c9d15cab01d7",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 6
            },
            {
               "length" : 5,
               "offset" : 30
            }
         ],
         "place_id" : "ChIJv0wpwp6tEmsR0Glcf5tugrk",
         "reference" : "ClRPAAAAYozD2iM3dQvDMrvrLDIALGoHO7v6pWhxn5vIm18pOyLLqToyikFov34qJoe4NnpoaLtGIWd5LWm5hOpWU1BT-SEI2jGZ8WXuDvYiFtQtjGMSEIR4thVlMws1tnNuE3hE2k0aFCqP_yHWRNSLqaP_vQFzazO-D7Hl",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Bondi Pizza"
            },
            {
               "offset" : 13,
               "value" : "Campbell Parade"
            },
            {
               "offset" : 30,
               "value" : "Sydney"
            },
            {
               "offset" : 38,
               "value" : "New South Wales"
            },
            {
               "offset" : 55,
               "value" : "Australia"
            }
         ],
         "types" : [ "establishment" ]
      }
   ],
     "status" : "OK"
  }
      

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

  • "status"는 요청의 메타데이터를 포함합니다. 아래의 상태 코드를 참조하세요.
  • predictions는 쿼리 예상 검색어 배열을 포함합니다. 이러한 결과에 대한 자세한 내용은 쿼리 자동완성 결과를 참조하세요.

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

XML
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>pizza near Sydney, New South Wales, Australia</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Sydney</value>
   <offset>11</offset>
  </term>
  <term>
   <value>New South Wales</value>
   <offset>19</offset>
  </term>
  <term>
   <value>Australia</value>
   <offset>36</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>6</offset>
   <length>4</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>pizza near Sydney, NS, Canada</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Sydney</value>
   <offset>11</offset>
  </term>
  <term>
   <value>NS</value>
   <offset>19</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>23</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>6</offset>
   <length>4</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
...additional results ...
 <prediction>
  <description>Bondi Pizza, Campbell Parade, Sydney, New South Wales, Australia</description>
  <type>establishment</type>
  <place_id>ChIJv0wpwp6tEmsR0Glcf5tugrk</place_id>
  <reference>ClRPAAAADqzkHp7ZNKcaFxP-foYYI5dix_sSaqfkUgxEYaJrB0ntyg704tMG8sEJjebhIVLW4viCsKtnlxiBrrFk9fxq0ruf4oUdQDfv7zwmS4P68KQSEPKUkFNTgit63QOGRYeElv4aFJnD0wN2thFO6XFRq2JsHzQEirvC</reference>
  <id>c478ed4e7cb075b307fdce4ad4f6c9d15cab01d7</id>
  <term>
   <value>Bondi Pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Campbell Parade</value>
   <offset>13</offset>
  </term>
  <term>
   <value>Sydney</value>
   <offset>30</offset>
  </term>
  <term>
   <value>New South Wales</value>
   <offset>38</offset>
  </term>
  <term>
   <value>Australia</value>
   <offset>55</offset>
  </term>
  <matched_substring>
   <offset>6</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>30</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

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

  • 단일 <status> 요소는 요청의 메타데이터를 포함합니다. 아래의 상태 코드를 참조하세요.
  • 0개 이상의 <prediction> 요소가 있으며, 각 요소는 단일 쿼리 예상 검색어에 대한 정보를 포함합니다. 이러한 결과에 대한 자세한 내용은 쿼리 자동완성 결과를 참조하세요.

애플리케이션에 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 결과에서, 이 이름은 대개 사업체 이름입니다.
  • terms는 반환된 설명의 각 섹션(설명의 한 섹션은 일반적으로 쉼표로 끝남)을 식별하는 검색어의 배열을 포함합니다. 배열의 각 항목에는 검색어의 텍스트를 포함하는 value 필드와, 설명에서 이 검색어의 시작 지점을 정의하는 유니코드 문자로 측정된 offset 필드가 있습니다.
  • matched_substringoffset 값과 length를 포함합니다. 이 필드는 예상 검색어 결과 텍스트에 입력된 검색어의 위치를 표시하므로, 원하는 경우 예상 검색어를 강조 표시할 수 있습니다.

예상 검색어 중 일부는 장소일 수 있으며, place_id, referencetype이 이러한 예상 검색어에 포함됩니다. 이러한 결과에 대한 자세한 내용은 장소 자동완성 결과를 참조하세요.

sensor 매개변수

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

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

location_on
Google Places API Web Service