장소 지오코딩

유럽 경제 지역 (EEA) 개발자

장소 지오코딩을 사용하면 장소 ID에서 주소를 가져올 수 있습니다.

장소 ID는 Google 지역 정보 데이터베이스 및 Google 지도에 있는 장소를 고유하게 나타냅니다. 주소를 지오코딩할 때 장소 ID를 가져옵니다. 장소 세부정보 (신규), 텍스트 검색 (신규), 주변 지역 검색(신규)과 같은 다른 여러 API에서 장소 ID를 검색할 수도 있습니다.

장소 지오코딩 요청

장소 지오코딩 요청은 다음과 같은 형태의 HTTP GET 요청입니다.

https://geocode.googleapis.com/v4beta/geocode/places/PLACE_ID

여기서 PLACE_ID에는 관심 위치의 장소 ID가 포함됩니다.

다른 모든 매개변수는 URL 매개변수로 전달하거나, API 키 또는 필드 마스크와 같은 매개변수의 경우 GET 요청의 일부로 헤더에 전달합니다. 예를 들면 다음과 같습니다.

https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY

또는 curl 명령어에서 다음을 입력합니다.

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

OAuth를 사용하여 요청하기

Geocoding API v4는 인증을 위해 OAuth 2.0을 지원합니다. Geocoding API에서 OAuth를 사용하려면 OAuth 토큰에 올바른 범위가 할당되어야 합니다. Geocoding API는 장소 지오코딩과 함께 사용할 수 있는 다음 범위를 지원합니다.

  • https://www.googleapis.com/auth/maps-platform.geocode — 모든 Geocoding API 엔드포인트와 함께 사용합니다.
  • https://www.googleapis.com/auth/maps-platform.geocode.place — 장소 지오코딩에 GeocodePlace와 함께만 사용합니다.

또한 모든 Geocoding API 엔드포인트에 일반 https://www.googleapis.com/auth/cloud-platform 범위를 사용할 수 있습니다. 이 범위는 모든 엔드포인트에 대한 액세스를 허용하는 일반 범위이므로 개발 중에는 유용하지만 프로덕션에서는 유용하지 않습니다.

자세한 내용과 예는 OAuth 사용을 참고하세요.

장소 지오코딩 응답

장소 지오코딩은 장소 ID에 해당하는 장소를 나타내는 GeocodeResult 객체를 반환합니다.

전체 JSON 객체는 다음 형식입니다.

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "addressComponents": [
    {
      "longText": "1600",
      "shortText": "1600",
      "types": [
        "street_number"
      ]
    },
    {
      "longText": "Amphitheatre Parkway",
      "shortText": "Amphitheatre Pkwy",
      "types": [
        "route"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Mountain View",
      "shortText": "Mountain View",
      "types": [
        "locality",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Santa Clara County",
      "shortText": "Santa Clara County",
      "types": [
        "administrative_area_level_2",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "California",
      "shortText": "CA",
      "types": [
        "administrative_area_level_1",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "United States",
      "shortText": "US",
      "types": [
        "country",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "94043",
      "shortText": "94043",
      "types": [
        "postal_code"
      ]
    }
  ],
  "types": [
    "establishment",
    "point_of_interest"
  ]
}

필수 매개변수

  • place: 인간이 읽을 수 있는 주소를 얻으려는 장소의 장소 ID입니다. 장소 ID는 다른 Google API에 사용할 수 있는 고유 식별자입니다. 예를 들어 Roads API에서 반환된 placeID를 사용하여 스냅된 지점의 주소를 가져올 수 있습니다. 장소 ID에 대한 자세한 내용은 장소 ID를 참고하세요.

선택적 매개변수

  • languageCode

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

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

    두 자리 CLDR 코드 값으로 된 지역 코드입니다. 기본값은 없습니다. 대부분의 CLDR 코드는 ISO 3166-1 코드와 동일합니다.

    주소를 지오코딩할 때(정방향 지오코딩) 이 매개변수는 서비스의 결과를 지정된 지역으로 제한하지는 않지만 영향을 줄 수 있습니다. 위치 또는 장소를 지오코딩할 때(역 지오코딩 또는 장소 지오코딩) 이 매개변수를 사용하여 주소 형식을 지정할 수 있습니다. 모든 경우에 이 매개변수는 관련 법규에 따라 결과에 영향을 줄 수 있습니다.