역 지오코딩은 지도 위치를 사람이 읽을 수 있는 주소로 변환합니다. 지도 위치는 위치의 위도 및 경도 좌표로 나타냅니다.
위치를 역지오코딩하면 응답에 다음이 포함됩니다.
이 API는 가장 구체적인 상세 주소부터 동네, 도시, 카운티, 주와 같이 덜 구체적인 독립체까지 다양한 유형의 주소를 반환합니다. 일반적으로 가장 정확한 주소가 첫 번째 결과로 표시됩니다. 특정 유형의 주소를 일치시키려면 types 매개변수를 사용하세요.
역 지오코딩 요청
역지오코딩 요청은 HTTP GET 요청입니다. 위치를 구조화되지 않은 문자열로 지정할 수 있습니다.
https://geocode.googleapis.com/v4beta/geocode/location/LATITUDE,LONGITUDE
또는 쿼리 매개변수로 표현되는 구조화된 위도 및 경도 좌표 집합으로 나타낼 수 있습니다.
https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE
일반적으로 HTML 양식으로 캡처된 위치 구성요소를 처리할 때 구조화된 형식을 사용합니다.
다른 모든 매개변수는 URL 매개변수로 전달하거나 API 키 또는 필드 마스크와 같은 매개변수의 경우 GET 요청의 일부로 헤더에 전달합니다. 예를 들면 다음과 같습니다.
구조화되지 않은 위치 문자열 전달
비구조화된 위치는 위도와 경도 좌표가 쉼표로 구분된 문자열 형식의 위치입니다.
https://geocode.googleapis.com/v4beta/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/v4beta/geocode/location/37.4225508,-122.0846338"
구조화된 위치 전달
LatLng 유형의 location 쿼리 매개변수를 사용하여 구조화된 위치를 지정합니다.
LatLng 객체를 사용하면 위도와 경도를 별도의 쿼리 매개변수로 지정할 수 있습니다.
https://geocode.googleapis.com/v4beta/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배열입니다.역 지오코더가
results배열에 두 개 이상의 결과를 반환합니다. 결과는 단순히 우편 주소가 아니라 위치를 지리적으로 명명하는 방법입니다. 예를 들어 시카고시의 한 지점을 지오코딩하는 경우 지오코딩된 지점은 상세 주소, 도시(시카고), 주 (일리노이) 또는 국가 (미국)로 표시될 수 있습니다. 지오코더에서는 이 모두가 다 '주소'입니다. 역 지오코더는 이러한 유형을 유효한 결과로 반환합니다.PlusCode유형의plusCode필드에는 요청의 위도와 경도에 가장 근접한 플러스 코드가 포함됩니다. 또한results배열의 각 요소에는 Plus Code가 포함되어 있습니다. 디코딩된 플러스 코드와 요청 지점 간의 거리가 10m 미만입니다.
전체 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
지역 코드입니다. 2자리 CLDR 코드 값으로 표현됩니다. 기본값은 없습니다. 대부분의 CLDR 코드는 ISO 3166-1 코드와 동일합니다.
주소를 지오코딩할 때(전방 지오코딩) 이 매개변수는 서비스의 결과를 지정된 지역으로 제한하지는 않지만 영향을 줄 수 있습니다. 위치 또는 장소를 지오코딩할 때, 역 지오코딩 또는 장소 지오코딩을 수행할 때 이 매개변수를 사용하여 주소 형식을 지정할 수 있습니다. 이 매개변수는 모든 경우에 적용되는 법규에 따라 결과에 영향을 줄 수 있습니다.
세부사항
Granularity에 정의된 대로 별도의 쿼리 매개변수로 지정된 하나 이상의 위치 세부사항입니다.granularity매개변수를 여러 개 지정하면 API는 세부사항과 일치하는 모든 주소를 반환합니다.granularity매개변수는 지정된 위치 세부사항으로 검색을 제한하지 않습니다. 대신granularity는 검색 후 필터 역할을 합니다. API는 지정된location의 모든 결과를 가져온 후 지정된 위치 세부사항과 일치하지 않는 결과를 삭제합니다.types와granularity를 모두 지정하면 API는 두 항목과 모두 일치하는 결과만 반환합니다. 예를 들면 다음과 같습니다.https://geocode.googleapis.com/v4beta/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/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2
&types=locality &key=API_KEY 다음과 같은 값이 지원됩니다.
주소 유형 및 주소 구성요소 유형
응답의
GeocodeResult본문에서types배열은 주소 유형을 나타냅니다. 주소 유형의 예로는 상세 주소, 국가, 행정 구역이 있습니다.GeocodeResult본문의AddressComponents필드에 있는types배열은 주소의 각 부분 유형을 나타냅니다. 예에는 번지 또는 국가가 포함됩니다.주소에는 여러 유형이 있을 수 있습니다. 이러한 유형은 '태그'로 간주될 수 있습니다. 예를 들어 많은 도시가
political및locality유형으로 태그됩니다.주소 유형과 주소 구성요소 유형 배열 모두에서 다음과 같은 유형이 지원되고 반환됩니다.
주소 유형 설명 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이름이 지정된 관심 장소입니다. 일반적으로 이러한 '관심 장소'는 '엠파이어 스테이트 빌딩' 또는 '에펠탑'과 같이 다른 카테고리에 쉽게 포함되지 않는 유명한 지역 항목입니다. 빈 유형 목록은 특정 주소 요소에 대해 알려진 유형이 없다는 것을 나타냅니다 (예: 프랑스의 리외디).