역 지오코딩 (주소 조회) 요청 및 응답

일반적으로 지오코딩이라는 용어는 사람이 읽을 수 있는 주소를 지도 위의 위치로 변환하는 과정을 나타냅니다. 반대로 지도상의 위치를 사람이 읽을 수 있는 주소로 변환하는 과정을 역 지오코딩이라고 합니다.

역 지오코딩 요청

필수 매개변수

  • latlng - 사람이 읽을 수 있는 가장 가까운 주소를 얻으려는 위치를 지정하는 위도 및 경도 좌표입니다.
  • key: 애플리케이션의 API 키입니다. 이 키는 할당량 관리를 위해 애플리케이션을 식별합니다. 키를 가져오는 방법을 알아보세요.

선택적 매개변수

다음은 역 지오코딩 요청에 포함할 수 있는 선택적 매개변수입니다.

  • language - 결과를 반환할 때 사용할 언어입니다.
    • 지원 언어 목록을 참고하세요. 지원되는 언어는 자주 업데이트되므로 이 목록은 완전하지 않을 수 있습니다.
    • language를 지정하지 않으면 지오코더는 Accept-Language 헤더에 지정된 기본 언어 또는 요청을 보낸 도메인의 기본 언어를 사용하려고 시도합니다.
    • 지오코더는 사용자와 현지인이 모두 읽을 수 있는 상세 주소를 제공하기 위해 최선을 다하고 있습니다. 이를 위해 필요한 경우 기본 언어를 준수하면서 사용자가 읽을 수 있는 스크립트로 음역된 현지 언어로 상세 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
    • 기본 언어로 이름을 사용할 수 없는 경우 지오코더는 가장 근접한 일치 항목을 사용합니다.
  • region - ccTLD('최상위 도메인') 2자리 값으로 지정되는 지역 코드입니다. 매개변수는 관련 법규에 따른 결과에도 영향을 줄 수 있습니다.
  • result_type - 파이프 (|)로 구분된 하나 이상의 주소 유형으로 구성된 필터입니다. 매개변수에 여러 주소 유형이 포함되어 있으면 API가 1개 이상의 유형과 일치하는 모든 주소를 반환합니다. 처리 관련 참고사항: result_type 매개변수는 검색을 지정된 주소 유형으로 restrict하지 않습니다. 대신 result_type는 검색 후 필터 역할을 합니다. API는 지정된 latlng의 모든 결과를 가져온 후 지정된 주소 유형과 일치하지 않는 결과를 삭제합니다. 다음과 같은 값이 지원됩니다.
    • street_address는 정확한 상세 주소를 나타냅니다.
    • route는 이름이 지정된 경로(예: 'US 101')를 나타냅니다.
    • intersection은 일반적으로 두 주요 도로의 주요 교차로를 나타냅니다.
    • political은 정치적 독립체를 나타냅니다. 일반적으로 이 유형은 특정 행정 구역의 다각형을 나타냅니다.
    • country는 전국적인 정치적 독립체를 나타내고 일반적으로 지오코더에서 반환하는 순위가 가장 높은 유형입니다.
    • administrative_area_level_1은 국가 수준 아래 첫 번째 행정 독립체를 나타냅니다. 미국에서 이 행정 구역 수준은 주입니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다. 대부분의 경우 administrative_area_level_1 짧은 이름은 ISO 3166-2 하위 구역이나 기타 널리 보급된 목록들과 거의 일치하지만 지오코딩 결과는 다양한 신호와 위치 데이터를 기반으로 하기 때문에 이러한 일치가 보장되지는 않습니다.
    • administrative_area_level_2는 국가 수준 아래 두 번째 행정 독립체를 나타냅니다. 미국에서 이 행정 구역 수준은 카운티입니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
    • administrative_area_level_3은 국가 수준 아래 세 번째 행정 독립체를 나타냅니다. 이 유형은 하위 행정 구역을 나타냅니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
    • administrative_area_level_4는 국가 수준 아래 네 번째 행정 독립체를 나타냅니다. 이 유형은 하위 행정 구역을 나타냅니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
    • administrative_area_level_5는 국가 수준 아래 다섯 번째 행정 독립체를 나타냅니다. 이 유형은 하위 행정 구역을 나타냅니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
    • administrative_area_level_6은 국가 수준 아래 여섯 번째 행정 독립체를 나타냅니다. 이 유형은 하위 행정 구역을 나타냅니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
    • administrative_area_level_7은 국가 수준 아래 일곱 번째 행정 독립체를 나타냅니다. 이 유형은 하위 행정 구역을 나타냅니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
    • colloquial_area는 일반적으로 사용되는 독립체의 대체 이름을 나타냅니다.
    • locality는 도시 또는 마을로 통합된 정치적 독립체를 나타냅니다.
    • sublocality는 지역 아래 첫 번째 행정 독립체를 나타냅니다. 일부 위치의 경우 추가 유형 중 하나(sublocality_level_1~sublocality_level_5)를 받을 수도 있습니다. 각 하위 지역 수준은 하나의 행정 독립체입니다. 숫자가 클수록 더 작은 지리적 영역을 나타냅니다.
    • neighborhood는 이름이 지정된 동네를 나타냅니다.
    • premise는 이름이 지정된 위치, 일반적으로 공통된 이름을 가진 건물 또는 여러 건물을 나타냅니다.
    • subpremise는 이름이 지정된 위치 아래 첫 번째 항목, 일반적으로 공통된 이름을 가진 여러 건물 중 한 건물을 나타냅니다.
    • plus_code는 위도와 경도에서 파생된 인코딩된 위치 참조를 나타냅니다. Plus Code는 상세 주소가 없는(건물에 번호가 지정되지 않거나 거리 이름이 없는) 장소의 상세 주소 대신 사용할 수 있습니다. 자세한 내용은 https://plus.codes를 참고하세요.
    • postal_code는 국가 내에서 우편물을 보낼 때 사용되는 우편번호를 나타냅니다.
    • natural_feature는 유명한 자연 지형지물을 나타냅니다.
    • airport는 공항을 나타냅니다.
    • park는 이름이 지정된 공원을 나타냅니다.
    • point_of_interest는 이름이 지정된 관심 장소를 나타냅니다. 일반적으로 이러한 '관심 장소'는 '엠파이어 스테이트 빌딩' 또는 '에펠탑'과 같이 다른 카테고리에 쉽게 포함되지 않는 유명한 지역 항목입니다.
  • location_type - 파이프 (|)로 구분된 하나 이상의 위치 유형으로 구성된 필터입니다. 매개변수에 여러 위치 유형이 포함된 경우 API는 1개 이상의 위치 유형과 일치하는 모든 주소를 반환합니다. 처리 참고사항: location_type 매개변수는 검색을 지정된 위치 유형으로 restrict하지 않습니다. 대신 location_type는 검색 후 필터 역할을 합니다. API는 지정된 latlng의 모든 결과를 가져온 후 지정된 위치 유형과 일치하지 않는 결과를 삭제합니다. 다음과 같은 값이 지원됩니다.
    • "ROOFTOP"는 상세 주소 수준까지 Google의 위치 정보가 정확한 주소만 반환합니다.
    • "RANGE_INTERPOLATED"는 두 정확한 점 (예: 교차로) 사이에 보간된 (일반적으로 도로에서) 근사값을 반영하는 주소만 반환합니다. 보간된 범위는 일반적으로 상세 주소에 옥상 지오코드를 사용할 수 없음을 나타냅니다.
    • "GEOMETRIC_CENTER"는 다중선 (예: 거리) 또는 다각형 (지역)과 같은 위치의 기하학적 중심만 반환합니다.
    • "APPROXIMATE"는 근사치로 특성이 지정된 주소만 반환합니다.

result_typelocation_type 필터가 모두 존재하면 API는 result_typelocation_type 값 둘 다와 일치하는 결과만 반환합니다. 허용되는 필터 값이 없으면 API는 ZERO_RESULTS를 반환합니다.

역 지오코딩의 예

다음 쿼리에는 브루클린의 어떤 위치에 대한 위도/경도 값이 포함됩니다.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

위의 쿼리는 다음과 같은 결과를 반환합니다.

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

역지오코더가 둘 이상의 결과를 반환한다는 점에 유의하세요. "formatted_address" 결과는 우편 주소가 아니라 위치를 지리적으로 명명하는 방법입니다. 예를 들어 시카고시의 한 지점을 지오코딩할 때 지오코딩된 지점은 상세 주소, 도시 (시카고), 주 (일리노이) 또는 국가 (미국)로 표시될 수 있습니다. 지오코더에게는 모든 것이 '주소'입니다. 역 지오코더는 이러한 유형을 유효한 결과로 반환합니다.

역 지오코더는 정치적 독립체 (국가, 주, 도시 및 동네), 상세 주소 및 우편번호를 매칭합니다.

이전 쿼리에서 반환된 formatted_address 값의 전체 목록은 아래와 같습니다.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

이 API는 가장 구체적인 상세 주소부터 인근 지역, 도시, 카운티, 주와 같은 덜 구체적인 정치적 항목에 이르기까지 다양한 유형의 주소를 반환합니다. 일반적으로 더 정확한 주소가 이 경우처럼 가장 눈에 띄는 결과입니다. 특정 유형의 주소와 일치시키려면 아래에서 유형별로 결과 제한 섹션을 참고하세요. 따라서 결과의 상대적 위치가 다를 수 있습니다.

유형별로 필터링된 역 지오코딩

다음 예에서는 반환된 주소를 필터링하여 위치 유형이 ROOFTOP이고 주소 유형이 street_address인 주소만 포함합니다.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

참고: 이 필터는 역 지오코딩에만 유효합니다.

역 지오코딩 응답

역 지오코딩 응답의 형식은 지오코딩 응답과 동일합니다. 지오코딩 응답을 참조하세요. 아래는 역지오코딩 응답에서 가능한 상태 코드입니다.

역 지오코딩 상태 코드

지오코딩 응답 객체의 "status" 필드에는 요청의 상태가 포함되며, 역 지오코딩이 작동하지 않는 원인을 추적하는 데 도움이 되는 디버깅 정보가 포함될 수도 있습니다. "status" 필드는 다음 값을 포함할 수 있습니다.

  • "OK"는 오류가 발생하지 않았으며 하나 이상의 주소가 반환되었음을 나타냅니다.
  • "ZERO_RESULTS"는 역 지오코딩에 성공했지만 반환된 결과가 없음을 나타냅니다. 이는 지오코더에 원격 위치의 latlng가 전달된 경우 발생할 수 있습니다.
  • "OVER_QUERY_LIMIT"는 할당량을 초과했음을 나타냅니다.
  • "REQUEST_DENIED"는 요청이 거부되었음을 나타냅니다. 요청에 result_type 또는 location_type 매개변수가 포함되어 있지만 API 키는 포함되어 있지 않기 때문일 수 있습니다.
  • "INVALID_REQUEST"는 일반적으로 다음 중 하나를 나타냅니다.
    • 쿼리 (address, components 또는 latlng)가 누락되었습니다.
    • 제공된 result_type 또는 location_type이 잘못되었습니다.
  • "UNKNOWN_ERROR"는 서버 오류로 인해 요청을 처리하지 못했음을 나타냅니다. 다시 시도하면 요청이 성공할 수도 있습니다.

역 지오코딩 플러스 코드

지오코딩 응답 내의 plus_code 필드에는 쿼리된 위도와 경도에 가장 근접한 플러스 코드가 포함됩니다. 또한 대부분의 경우 JSON 결과 배열에는 plus_code 유형의 전체 지오코딩 결과와 플러스 코드가 포함된 주소가 포함됩니다. 디코딩된 플러스 코드와 요청 지점 사이의 거리는 10미터 미만이 되도록 보장됩니다.