위치 역 지오코딩

유럽 경제 지역 (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"

구조화된 위치 전달

location 쿼리 매개변수를 사용하여 구조화된 위치를 지정합니다. 유형 LatLng 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 범위를 사용할 수 있습니다. 이 범위는 모든 메서드에 액세스할 수 있는 일반 범위이므로 개발 중에는 유용하지만 프로덕션에는 유용하지 않습니다.

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

역 지오코딩 응답

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

  • 장소를 나타내는 results 객체의 GeocodeResult 배열

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

    1. GeocodeResult.types: 이 배열은 결과의 전반적인 유형을 나타냅니다. 가능한 값은 Places API에서 사용하는 장소 유형에서 가져옵니다. 자세한 내용은 장소 유형 표 A 및 B를 참고하세요.
    2. GeocodeResult.addressComponents[].types: 각 주소 구성요소에는 주소의 특정 부분을 나타내는 types 배열이 있습니다. 이러한 값은 주소 유형 및 주소 구성요소 유형 표에서 가져옵니다.

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

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

    참고: 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"
    },
    ...
  ]
}

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