위치 역 지오코딩

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

역 지오코딩은 지도 위치를 사람이 읽을 수 있는 주소로 변환합니다. 위치의 위도 및 경도 좌표로 지도 위치를 나타냅니다.

위치를 역지오코딩하면 응답에 다음이 포함됩니다.

이 API는 가장 구체적인 상세 주소부터 동네, 도시, 카운티, 주와 같이 덜 구체적인 독립체까지 다양한 유형의 주소를 반환합니다. 가장 정확한 주소가 일반적으로 첫 번째 결과입니다. 특정 유형의 주소를 일치시키려면 types 매개변수를 사용합니다.

역 지오코딩 요청

리버스 지오코딩 요청은 HTTP GET 요청입니다. 위치를 구조화되지 않은 문자열로 지정할 수 있습니다.

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

또는 쿼리 매개변수로 표현되는 구조화된 위도 및 경도 좌표 집합으로도 사용할 수 있습니다.

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

일반적으로 HTML 양식에서 캡처된 위치 구성요소를 처리할 때는 구조화된 형식을 사용합니다.

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

구조화되지 않은 위치 문자열 전달

구조화되지 않은 위치는 위도 및 경도 좌표의 쉼표로 구분된 문자열로 형식이 지정된 위치입니다.

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=API_KEY

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

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

구조화된 위치 전달

LatLng 유형의 location 쿼리 매개변수를 사용하여 구조화된 위치를 지정합니다. LatLng 객체를 사용하면 위도와 경도를 별도의 쿼리 매개변수로 지정할 수 있습니다.

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

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.location — 역 지오코딩을 위해 GeocodeLocation와 함께만 사용합니다.

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

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

역 지오코딩 응답

역지오코딩은 다음을 포함하는 GeocodeLocationResponse 객체를 반환합니다.

  • 장소를 나타내는 GeocodeResult 객체의 results 배열입니다.

    Geocoding API 응답에는 GeocodeResult 내의 두 가지 주요 위치에 types 배열이 포함됩니다.

    1. GeocodeResult.types: 이 배열은 결과의 전체 유형을 나타냅니다. 가능한 값은 장소 유형 (신규) 페이지의 표 A 및 표 B에서 가져옵니다.
    2. GeocodeResult.addressComponents[].types: 각 주소 구성요소에는 주소의 특정 부분의 유형을 나타내는 types 배열이 있습니다. 이러한 값은 장소 유형 (신규) 페이지의 주소 유형 및 주소 구성요소 유형 표에서 가져옵니다.

    역 지오코더는 results 배열에 두 개 이상의 결과를 반환합니다. 결과는 단순히 우편 주소가 아니라 위치를 지리적으로 명명하는 방법입니다. 예를 들어 시카고시의 한 지점을 지오코딩하는 경우 지오코딩된 지점은 상세 주소, 도시(시카고), 주 (일리노이) 또는 국가 (미국)로 표시될 수 있습니다. 지오코더에서는 이 모두가 다 '주소'입니다. 역 지오코더는 이러한 유형을 유효한 결과로 반환합니다.

  • PlusCode 유형의 plusCode 필드에는 요청의 위도와 경도를 가장 잘 근사하는 플러스 코드가 포함됩니다. 또한 results 배열의 각 요소에는 플러스 코드가 포함됩니다. 디코딩된 Plus Code와 요청 지점 간 거리가 10미터 미만입니다.

    참고: API가 항상 플러스 코드를 반환하는 것은 아닙니다.

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

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

필수 매개변수

  • 위치

    인간이 읽을 수 있는 가장 가까운 주소를 원하는 위치를 지정하는 위도 및 경도 좌표입니다.

선택적 매개변수

  • languageCode

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

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

  • regionCode

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

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

  • 세부사항

    Granularity에 정의된 대로 별도의 쿼리 매개변수로 지정된 하나 이상의 위치 세부사항입니다. granularity 매개변수를 여러 개 지정하면 API는 세부사항 중 하나와 일치하는 모든 주소를 반환합니다.

    granularity 매개변수는 검색을 지정된 위치 세부사항으로 제한하지 않습니다. 대신 granularity는 검색 후 필터로 작동합니다. API는 지정된 location의 모든 결과를 가져온 다음 지정된 위치 세부사항과 일치하지 않는 결과를 삭제합니다.

    types와 granularity을 모두 지정하면 API는 두 가지 모두와 일치하는 결과만 반환합니다. 예를 들면 다음과 같습니다.

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • 유형

    하나 이상의 주소 유형으로, 별도의 쿼리 매개변수로 지정됩니다. 가능한 값은 장소 유형 (신규) 페이지의 주소 유형 및 주소 구성요소 유형 표에서 가져옵니다. types 매개변수를 여러 개 지정하면 API는 유형 중 하나와 일치하는 모든 주소를 반환합니다.

    types 매개변수는 검색을 지정된 주소 유형으로 제한하지 않습니다. 대신 types는 검색 후 필터로 작동합니다. API는 지정된 위치의 모든 결과를 가져온 다음 지정된 주소 유형과 일치하지 않는 결과를 삭제합니다.

    types와 granularity를 모두 지정하면 API는 두 가지 모두와 일치하는 결과만 반환합니다. 예를 들면 다음과 같습니다.

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • FieldMask

    응답 필드 마스크를 만들어 응답에서 반환할 필드를 지정합니다. URL 매개변수 $fields 또는 fields를 사용하거나 HTTP 헤더 X-Goog-FieldMask를 사용하여 응답 필드 마스크를 메서드에 전달합니다. 예를 들어 아래 요청은 응답의 placeID 필드만 반환합니다.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    대답은 다음과 같습니다. 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

    자세한 내용은 반환할 필드 선택을 참고하세요.