일반적으로 지오코딩이라는 용어는 사람이 읽을 수 있는 주소를 지도상의 위치로 변환하는 과정을 가리킵니다. 그 반대로 지도상의 위치를 사람이 읽을 수 있는 주소로 변환하는 프로세스를 역지오코딩이라고 합니다.
역지오코딩 요청
필수 매개변수
latlng: 사람이 읽을 수 있는 가장 가까운 주소를 가져오려는 위치를 지정하는 위도 및 경도 좌표입니다.key: 애플리케이션의 API 키입니다. 이 키는 할당량 관리를 위해 애플리케이션을 식별합니다. 키를 가져오는 방법을 알아보세요.
선택적 매개변수
역지오코딩 요청에 포함할 수 있는 선택적 매개변수는 다음과 같습니다.
language— 결과 반환 시 사용되는 언어입니다.- 지원되는 언어 목록을 참고하세요. 지원되는 언어는 자주 업데이트되므로 목록이 완전하지 않을 수 있습니다.
language를 지정하지 않으면 지오코더는Accept-Language헤더에 지정된 기본 언어를 사용하거나 요청을 보낸 도메인의 기본 언어를 사용하려고 시도합니다.- 지오코더는 사용자와 현지인이 모두 읽을 수 있는 거리 주소를 제공하려고 최선을 다합니다. 이를 위해 API는 기본 언어를 준수하면서 필요한 경우 사용자가 읽을 수 있는 스크립트로 음차한 현지 언어로 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
- 기본 언어로 이름을 사용할 수 없는 경우 지오코더는 가장 유사한 일치 항목을 사용합니다.
region: 지역 코드로, ccTLD('최상위 도메인') 두 문자 값으로 지정됩니다. 이 매개변수는 관련 법규에 따라 결과에 영향을 미칠 수도 있습니다.result_type: 파이프 (|)로 구분된 하나 이상의 주소 유형 필터입니다. 매개변수에 여러 주소 유형이 포함된 경우 API는 이러한 유형과 일치하는 모든 주소를 반환합니다. 처리에 관한 참고사항:result_type매개변수는 지정된 주소 유형으로 검색을 제한하지 않습니다. 대신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는 이러한 유형과 일치하는 모든 주소를 반환합니다. 처리에 관한 참고사항:location_type매개변수는 검색을 지정된 위치 유형으로 제한하지 않습니다. 대신location_type는 검색 후 필터 역할을 합니다. API는 지정된latlng의 모든 결과를 가져온 다음 지정된 위치 유형과 일치하지 않는 결과를 삭제합니다. 다음 값이 지원됩니다."ROOFTOP"는 Google이 거리 주소 수준의 정밀도로 정확한 위치 정보를 보유한 주소만 반환합니다."RANGE_INTERPOLATED"는 일반적으로 도로에서 정확한 두 지점(예: 교차로) 간에 보간된 근사값을 반영하는 주소만 반환합니다. 보간된 범위는 일반적으로 거리 주소에 루프톱 지오코드를 사용할 수 없음을 나타냅니다."GEOMETRIC_CENTER"는 폴리라인 (예: 거리) 또는 폴리곤 (지역)과 같은 위치의 기하학적 중심만 반환합니다."APPROXIMATE"는 대략적인 것으로 특성화된 주소만 반환합니다.
extra_computations: 이 매개변수를 사용하여 응답에 다음과 같은 추가 기능을 지정합니다.ADDRESS_DESCRIPTORS: 자세한 내용은 주소 설명자를 참고하세요.BUILDING_AND_ENTRANCES: 자세한 내용은 입구 및 건물 윤곽을 참고하세요.
extra_computations매개변수를 포함합니다. 예를 들면 다음과 같습니다.extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
result_type 및 location_type 필터가 모두 있는 경우 API는 result_type 및 location_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 역지오코딩
지오코딩 응답 내의 plus_code 필드에는 쿼리된 위도와 경도에 가장 근접한 플러스 코드가 포함됩니다.
또한 JSON 결과 배열에는 대부분의 경우 plus_code 유형과 플러스 코드가 포함된 주소가 있는 전체 지오코딩 결과가 포함됩니다. 디코딩된 Plus 코드와 요청 지점 간의 거리는 10미터 미만이어야 합니다.