모든 준비를 마쳤습니다!

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

Google Places API Web Service 활성화

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

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

장소 추가

장소를 추가하여 Google Maps 데이터베이스의 데이터에 애플리케이션의 데이터를 추가할 수 있습니다. 그러면 다음 작업이 가능합니다.

  • Google 데이터베이스에 저장된 데이터를 즉시 업데이트할 수 있습니다.
  • 새 장소를 Google Places 데이터베이스에 추가하기 위해 중재 큐로 전송할 수 있습니다.
  • 유사한 기능을 가진 다른 앱과 애플리케이션을 차별화할 수 있습니다.
  • 특정 사용자층이나 지리적 위치를 목표로 하는 애플리케이션을 만들 수 있습니다.
  • 본인의 애플리케이션에서 실행한 장소 검색 결과에 영향을 미칠 수 있습니다.
  1. 개요
  2. 장소 추가
  3. 장소 삭제
  4. 상태 코드
  5. 오류 메시지
  6. sensor 매개변수

개요

장소를 추가하면 자신의 애플리케이션에서 시작한 주변 검색에서 즉시 새 장소를 사용할 수 있습니다. 또한 새 장소가 Google 지도에 추가를 위해 중재 큐에 입력됩니다. 새로 추가된 장소는 중재 절차가 완료되기 전까지는 텍스트 검색, 레이더 검색 결과 또는 다른 애플리케이션에 표시되지 않습니다.

중재가 완료되기 전까지 애플리케이션에서 추가한 장소를 삭제할 수도 있습니다. 중재가 완료되고 Google 데이터베이스에 추가되면 더 이상 장소를 삭제할 수 없습니다. 승인되지 않은 장소는 계속해서 승인을 요청한 애플리케이션에 표시됩니다.

장소 추가

장소 추가 요청은 아래의 예시와 유사한 HTTP POST 요청입니다.


JSON
POST https://maps.googleapis.com/maps/api/place/add/json?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

{
  "location": {
    "lat": -33.8669710,
    "lng": 151.1958750
  },
  "accuracy": 50,
  "name": "Google Shoes!",
  "phone_number": "(02) 9374 4000",
  "address": "48 Pirrama Road, Pyrmont, NSW 2009, Australia",
  "types": ["shoe_store"],
  "website": "http://www.google.com.au/",
  "language": "en-AU"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/add/xml?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

<PlaceAddRequest>
  <location>
    <lat>-33.8669710</lat>
    <lng>151.1958750</lng>
  </location>
  <accuracy>50</accuracy>
  <name>Google Shoes!</name>
  <phone_number>(02) 9374 4000</phone_number>
  <address>48 Pirrama Road, Pyrmont, NSW 2009, Australia</address>
  <type>shoe_store</type>
  <website>http://www.google.com.au/</website>
  <language>en-AU</language>
</PlaceAddRequest>
      

URL 경로는 다음과 같은 입력 및 출력 형식을 나타냅니다.

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

URL은 다음과 같은 매개변수를 포함해야 합니다.

  • key — 애플리케이션의 API 키. 이 키는 할당량 관리 목적으로 애플리케이션을 식별하고 애플리케이션에서 추가한 장소를 앱에서 즉시 사용할 수 있도록 합니다. 자세한 내용은 키 가져오기를 참조하세요.

요청 본문에는 장소에 대한 정보가 있습니다. 지정된 output 매개변수에 따라 구성되어야 합니다(JSON 또는 XML).

  • accuracy — 이 요청이 기반으로 하는 위치 신호의 정확도(미터 단위로 표시).
  • address(중재 통과 가능성을 높이고자 할 경우 권장) — 추가하려는 장소의 주소. 장소가 올바른 형식이며 사람이 읽을 수 있는 형태로 제공되면 중재 절차를 통과하고 Google 지도 데이터베이스에 포함될 가능성이 높습니다.
  • language — 장소의 이름이 보고되는 언어. 지원되는 언어 목록 및 관련 코드를 참조하세요. 지원되는 언어는 자주 업데이트되므로 목록이 완전하지 않을 수 있습니다.
  • location(필수) — 추가하려는 장소의 지리적 위치로, 위도 및 경도 값으로 지정됩니다.
  • name(필수) — 장소의 전체 텍스트 이름. 최대 255자까지 입력할 수 있습니다.
  • phone_number(중재 통과 가능성을 높이기 위해 권장) — 장소와 연관된 전화번호. 장소에 올바른 형식의 전화번호가 있으면 중재 절차를 통과하고 Google 지도 데이터베이스에 포함될 가능성이 높습니다. 이 번호는 현지 전화번호 형식이나 국제 전화번호 형식이어야 합니다.
    • 현지 형식은 국가별로 다를 수 있습니다. Wikipedia 기사를 참조하세요. 예를 들어, Google 호주 시드니 지사의 현지 전화번호는 (02) 9374 4000입니다.
    • 국제 형식에는 국가 코드가 포함되며 플러스(+) 부호가 접두사로 붙습니다. 예를 들어, Google 호주 시드니 지사의 국제 전화번호 표기 형식은 +61 2 9374 4000입니다.
  • types(필수) — 장소가 속한 범주. types는 배열로 표시되지만 현재 한 장소에 대해 한 가지 유형만 지정할 수 있습니다. XML 요청에는 단일 <type> 요소가 필요합니다. 자세한 내용은 지원 유형 목록을 참조하세요. 장소가 지원되는 유형과 일치하지 않으면 other로 지정할 수 있습니다.
  • website(중재 통과 가능성을 높이기 위해 권장) — 사업체 홈페이지 등 같은 이 장소의 대표 웹사이트를 가리키는 URL. 장소가 올바른 형식이며 사람이 읽을 수 있는 형태로 제공되면 중재 절차를 통과하고 Google 지도 데이터베이스에 포함될 가능성이 높습니다.

장소 추가 응답

장소 추가 응답은 요청의 URL 경로에서 output 매개변수에서 지정한 형식으로 반환됩니다.

API는 상태 코드를 반환하며 요청이 성공적이면 응답에 새 장소에 대한 다음 속성이 포함됩니다.

  • place_id: 장소를 고유하게 식별하는 텍스트 식별자. 장소에 관한 정보를 검색하려면 이 식별자를 장소 세부정보 요청의 placeId 필드에 삽입해 전달합니다. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참조하세요.
  • scope: place_id의 범위를 나타냅니다. 이 필드에 사용할 수 있는 값은 다음과 같습니다.
    • APP: 장소 ID는 본인 애플리케이션에서만 인식됩니다. 참고: 아직 중재 절차를 통과하지 않았으므로 장소 추가 응답은 항상 APP 범위를 갖게 됩니다.
    • GOOGLE: 장소 ID를 다른 애플리케이션과 Google 지도에서 사용할 수 있습니다. 위에 언급한 것처럼 장소 추가 응답은 Google 전체 범위에는 포함되지 않습니다.
  • reference: 장소에 관한 추가 정보를 검색할 때 사용하는 고유 토큰입니다. 참고: reference는 이제 지원이 중단되고 place_id로 대체됩니다. 이 페이지의 사용 중단 알림을 참조하세요.
  • id: 이 장소를 표시하는 안정적인 고유 식별자. 이 식별자는 이 장소에 대한 정보를 검색하는 데 사용할 수 없지만 여러 세션에서 유효합니다. 이 장소에 대한 데이터를 통합하고 개별 검색에서 장소의 ID를 확인하는 데 사용할 수 있습니다. 참고: id는 이제 지원이 중단되고 place_id로 대체됩니다. 이 페이지의 사용 중단 알림을 참조하세요.
{
  "status": "OK",
  "place_id": "CdIJN2t_tDeuEmsRUsoyG83frY4",
  "scope": "APP",
  "reference": "CiQgAAAAeTQS1RtzAyVRVjHcRiIWmWeqcAl3k7bluW7GINLDULESEHozTQhy6OHJw03ziDvY1uEaFAP_vDRhK-UbWw3Gd7Ulqm3eRjIs",
  "id": "6947fc4007436a71dbda51ef9a58627c8e8858f9"
}

장소 삭제

다음 경우에만 장소를 삭제할 수 있습니다.

  • 삭제를 요청 중인 애플리케이션에서 장소를 추가한 경우.
  • 장소 추가 요청이 Google 지도 중재 절차를 통과하지 못했으며, 따라서 장소를 추가한 애플리케이션에만 표시되는 경우.

이 기준을 충족하지 않는 장소를 삭제하려고 하면, API가 REQUEST_DENIED 상태 코드를 반환합니다.

장소 삭제 요청은 다음 형식을 사용하는 HTTP POST 요청입니다.


JSON
POST https://maps.googleapis.com/maps/api/place/delete/json?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

{
  "place_id": "place ID"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/delete/xml?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

<PlaceDeleteRequest>
  <place_id>place ID</place_id>
</PlaceDeleteRequest>
      

URL 경로는 다음과 같은 입력 및 출력 형식을 나타냅니다.

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

URL은 다음과 같은 매개변수를 포함해야 합니다.

  • key — 애플리케이션의 API 키. 이 키는 할당량 관리 목적으로 애플리케이션을 식별하고 애플리케이션에서 추가한 장소를 앱에서 즉시 사용할 수 있도록 합니다. 자세한 내용은 키 가져오기를 참조하세요.

요청 본문은 지정된 output 매개변수에 따라 구성되어야 합니다(JSON 또는 XML). 다음 두 필드 중 하나를 포함해야 합니다.

  • place_id: 장소 검색에서 반환된 삭제해야 할 장소를 식별하는 문자열. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참조하세요.
  • 또는 reference를 지정하여 장소를 식별할 수도 있습니다. reference는 이제 지원이 중단되고 place_id로 대체됩니다. 이 페이지의 사용 중단 알림을 참조하세요.

장소 삭제 응답

장소 삭제 응답은 요청의 URL 경로에서 output 매개변수에서 지정한 형식으로 반환됩니다.

성공적인 삭제 요청은 다음과 같은 상태 코드를 반환합니다.

{
  "status": "OK"
}

상태 코드

장소 추가/삭제 요청의 상태 코드는 다음과 같습니다.

  • OK는 오류가 발생하지 않았으며, 장소가 성공적으로 보고되었음을 나타냅니다.
  • UNKNOWN_ERROR는 서버측 오류를 나타냅니다. 다시 시도하면 성공할 수도 있습니다.
  • OVER_QUERY_LIMIT는 할당량이 초과되었음을 나타냅니다.
  • REQUEST_DENIED는 요청이 거부되었음을 나타냅니다. 이는 다른 애플리케이션에서 추가되었거나 Google 지도 중재 절차를 통과한 장소를 삭제하려고 하는 경우 발생할 수 있습니다.
  • INVALID_REQUEST는 일반적으로 요청에 누락된 매개변수가 있음을 나타냅니다. 이 코드는 name이 255자를 초과하는 장소를 추가하는 경우에도 반환됩니다.
  • NOT_FOUND는 장소 삭제 요청시 반환될 수 있으며, 전달된 참조를 장소로 해석하지 못했음을 나타냅니다.

오류 메시지

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

sensor 매개변수

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

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

location_on
Google Places API Web Service