요청
Geocoding API 요청의 형식은 다음과 같습니다.
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
여기서 outputFormat
은 다음 값 중 하나일 수 있습니다.
json
(권장): JSON (JavaScript Object Notation) 형식으로 출력을 나타냅니다.xml
: XML 형식으로 출력을 나타냅니다.
HTTPS가 필요합니다.
일부 매개변수는 필수인 반면 일부 매개변수는 선택 사항입니다. URL 표준 형식과 마찬가지로, 매개변수는 앰퍼샌드 (&
) 문자를 사용하여 구분합니다.
각 요청 유형에 대해 다른 매개변수가 사용되므로, 이 페이지의 나머지 부분에서는 지오코딩과 역지오코딩에 대해 별도로 설명합니다.
지오코딩 (위도/경도 조회) 매개변수
지오코딩 요청의 필수 매개변수:
key
: 애플리케이션의 API 키입니다. 이 키는 할당량 관리를 위해 애플리케이션을 식별합니다. 키를 가져오는 방법을 알아보세요.요청에서
address
또는components
또는 둘 다를 지정해야 합니다.address
- 지오코딩할 상세 주소 또는 플러스 코드입니다. 해당 국가의 국내 우편 서비스에서 사용하는 형식에 따라 주소를 지정합니다. 사업체 이름과 부서, 스위트 번호 또는 층 번호와 같은 추가적인 주소 요소는 피해야 합니다. 상세 주소 요소는 공백으로 구분해야 합니다(여기서는 URL 이스케이프 처리되어%20
로 표시됨). 여기에 표시된 대로 Plus Code의 형식을 지정합니다. 더하기 기호는address=24%20Sussex%20Drive%20Ottawa%20ON
%2B
로 URL 이스케이프 처리되고 공백은%20
로 URL 이스케이프 처리됩니다.- 글로벌 코드는 4자리 지역 코드와 6자 이상의 로컬 코드입니다 (849VCWC8+R9는
849VCWC8%2BR9
입니다). - 복합 코드는 명시적인 위치가 포함된 6자 이상의 로컬 코드입니다 (CWC8+R9 Mountain View, CA, USA는
CWC8%2BR9%20Mountain%20View%20CA%20USA
입니다).
- 글로벌 코드는 4자리 지역 코드와 6자 이상의 로컬 코드입니다 (849VCWC8+R9는
components
: 파이프 (|
)로 구분된 요소가 있는 구성요소 필터입니다.address
가 제공되는 경우 구성요소 필터는 선택적 매개변수로 허용됩니다. 구성요소 필터의 각 요소는component:value
쌍으로 구성되며 지오코더의 결과를 완전히 제한합니다. 자세한 내용은 아래의 구성요소 필터링을 참고하세요.
자세한 안내는 FAQ를 참고하세요.
지오코딩 요청의 선택적 매개변수:
bounds
- 지오코딩 결과가 더 눈에 띄게 편향되는 뷰포트의 경계 상자입니다. 이 매개변수는 지오코더의 결과에 영향만 미치며, 결과를 완전히 제한하지는 않습니다. (자세한 내용은 아래의 뷰포트 편중을 참고하세요.)language
— 결과를 반환할 언어입니다.- 지원되는 언어 목록을 참고하세요. 지원되는 언어는 자주 업데이트되므로 목록이 완전하지 않을 수 있습니다.
language
를 지정하지 않으면 지오코더는Accept-Language
헤더에 지정된 기본 언어를 사용하거나 요청을 보낸 도메인의 기본 언어를 사용하려고 시도합니다.- 지오코더는 사용자와 현지인이 모두 읽을 수 있는 거리 주소를 제공하려고 최선을 다합니다. 이를 위해 API는 기본 언어를 준수하면서 필요한 경우 사용자가 읽을 수 있는 스크립트로 음차한 현지 언어로 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
- 기본 언어로 이름을 사용할 수 없는 경우 지오코더는 가장 유사한 일치 항목을 사용합니다.
- 기본 언어는 API가 반환하려고 선택한 결과 집합과 반환 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 유효하거나 유효하지 않을 수 있는 동의어 또는 거리 유형에 대한 약어와 같이 언어에 따라 다르게 약어를 해석합니다. 예를 들어 utca와 tér는 헝가리어로 각각 거리와 광장에 대한 동의어입니다.
region
: 지역 코드로, ccTLD('최상위 도메인') 두 문자 값으로 지정됩니다. 이 매개변수는 지오코더의 결과에 영향만 미치며, 결과를 완전히 제한하지는 않습니다. 자세한 내용은 아래의 지역 편중을 참고하세요. 이 매개변수는 관련 법규에 따라 결과에 영향을 미칠 수도 있습니다.components
— 요소가 파이프 (|
)로 구분된 구성요소 필터입니다. 요청에address
가 포함되지 않은 경우 구성요소 필터가 필수입니다. 구성요소 필터의 각 요소는component:value
쌍으로 구성되며 지오코더의 결과를 완전히 제한합니다. 자세한 내용은 아래의 구성요소 필터링을 참고하세요.extra_computations
: 이 매개변수를 사용하여 응답에 다음과 같은 추가 기능을 지정합니다.ADDRESS_DESCRIPTORS
: 자세한 내용은 주소 설명자를 참고하세요.BUILDING_AND_ENTRANCES
: 자세한 내용은 입구 및 건물 윤곽을 참고하세요.
extra_computations
매개변수를 포함합니다. 예를 들면 다음과 같습니다.extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
대답
지오코딩 응답은 URL 요청 내 output
플래그에서 지정한 형식으로 반환되며 기본적으로 JSON 형식으로 반환됩니다.
이 예시에서 Geocoding API는 '1600 Amphitheatre Parkway, Mountain View, CA' 주소에 대한 쿼리에 대해 json
응답을 요청합니다.
이 요청은 JSON output
플래그 사용을 보여줍니다.
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
이 요청은 XML output
플래그 사용을 보여줍니다.
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
아래 탭을 선택하여 샘플 JSON 및 XML 응답을 살펴보세요.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ] }, { "long_name": "California", "short_name": "CA", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
참고로, JSON 응답은 다음 두 가지 루트 요소를 포함합니다.
"status"
에는 요청에 대한 메타데이터가 포함됩니다. 아래의 상태 코드를 참고하세요."results"
에는 지오코딩된 주소 정보와 기하학적 정보의 배열이 포함됩니다.
일반적으로 주소 조회 시에 "results"
배열의 단 한 항목만 반환되지만, 주소 쿼리가 모호한 경우에는 지오코더가 여러 결과를 반환할 수도 있습니다.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
참고로, XML 응답은 단일 <GeocodeResponse>
요소와 두 개의 최상위 요소로 구성됩니다.
<status>
에는 요청에 대한 메타데이터가 포함됩니다. 아래의 상태 코드를 참고하세요.- 0개 이상의
<result>
요소가 있으며, 각 요소에는 지오코딩된 주소 정보와 기하학적 정보의 단일 집합이 포함됩니다.
XML 응답은 JSON 응답보다 상당히 더 깁니다. 따라서 서비스에 xml
이 꼭 필요한 경우가 아니라면 json
을 기본 출력 플래그로 사용하는 것이 좋습니다.
또한 XML 트리를 처리할 때는 올바른 노드와 요소를 참조하도록 주의해야 합니다. 출력 처리에 권장되는 디자인 패턴은
XPath로 XML 구문 분석을 참고하세요.
- XML 결과는 루트
<GeocodeResponse>
요소에 래핑됩니다. - JSON은 여러 개의 요소가 있는 항목을 복수의 배열 (
types
)로 나타내는 반면, XML은 여러 개의 단일 요소 (<type>
)를 사용하여 항목을 나타냅니다. - JSON에서는 빈 요소가 빈 배열로 나타나지만, XML에서는 이러한 요소가 없습니다. 결과를 생성하지 않는 응답은 JSON에서 빈
results
배열을 반환하지만, XML에서는<result>
요소가 없습니다.
상태 코드
지오코딩 응답 객체 내의 "status"
필드는 요청의 상태를 포함하며, 지오코딩이 작동하지 않는 원인을 추적하는 데 도움이 되는 디버깅 정보를 포함할 수 있습니다. "status"
필드에는 다음 값이 포함될 수 있습니다.
"OK"
는 오류가 발생하지 않았음을 나타냅니다. 주소가 성공적으로 파싱되었고 한 개 이상의 지오코드가 반환되었습니다."ZERO_RESULTS"
는 지오코딩이 성공했지만 반환된 결과가 없음을 나타냅니다. 지오코더가 존재하지 않는address
에 전달된 경우 이러한 결과가 발생할 수도 있습니다.OVER_DAILY_LIMIT
는 다음 중 하나를 나타냅니다.- API 키가 누락되었거나 잘못되었습니다.
- 계정에 결제가 사용 설정되지 않았습니다.
- 자체 적용되는 사용량 한도를 초과했습니다.
- 제공된 결제 수단이 더 이상 유효하지 않습니다 (예: 신용카드가 만료됨).
이 문제를 해결하는 방법은 지도 FAQ를 참고하세요.
"OVER_QUERY_LIMIT"
는 할당량을 초과했음을 나타냅니다."REQUEST_DENIED"
는 요청이 거부되었음을 나타냅니다."INVALID_REQUEST"
는 일반적으로 쿼리(address
,components
또는latlng
)가 누락되었음을 나타냅니다."UNKNOWN_ERROR"
는 서버 오류로 인해 요청을 처리하지 못했음을 나타냅니다. 다시 시도하면 요청이 성공할 수도 있습니다.
오류 메시지
지오코더가 OK
이외의 상태 코드를 반환하면 지오코딩 응답 객체 내에 추가 error_message
필드가 있을 수 있습니다. 이 필드에는 지정된 상태 코드가 제시된 이유에 대한 상세정보가 포함되어 있습니다.
결과
지오코더가 결과를 반환할 때, (JSON) results
배열 내에 결과를 넣습니다. 지오코더에서 결과를 반환하지 않는 경우에도 (예: 주소가 존재하지 않는 경우) 여전히 빈 results
배열을 반환합니다. (XML 응답은 0개 이상의 <result>
요소로 구성됩니다.)
일반적인 결과에는 다음 필드가 포함됩니다.
types[]
배열은 반환된 결과의 유형을 나타냅니다. 이 배열에는 결과에 반환되는 지형지물의 유형을 나타내는 0개 이상의 태그 집합이 포함됩니다. 예를 들어 '시카고'의 지오코드는 '시카고'가 도시임을 나타내는 'locality'를 반환하고 시카고가 정치적 독립체임을 나타내는 'political'도 반환합니다. 해당 주소 요소에 알려진 유형이 없는 경우 구성요소에 빈 유형 배열이 있을 수 있습니다. API는 필요에 따라 새 유형 값을 추가할 수 있습니다. 자세한 내용은 주소 유형 및 주소 구성요소를 참고하세요.formatted_address
는 이 위치의 사람이 읽을 수 있는 주소가 포함된 문자열입니다.이 주소는 대개 우편 주소와 일치합니다. 참고: 영국과 같은 일부 국가에서는 라이선스 제한으로 인해 실제 우편 주소의 배포가 허용되지 않습니다.
형식이 지정된 주소는 하나 이상의 주소 구성요소로 논리적으로 구성됩니다. 예를 들어 주소 '111 8th Avenue, New York, NY'는 '111'(번지), '8th Avenue'(경로), 'New York'(도시) 및 'NY'(미국의 주)로 구성됩니다.
형식이 지정된 주소를 프로그래매틱 방식으로 파싱하지 마세요. 대신 API 응답에 형식이 지정된 주소 필드 외에 포함되는 개별 주소 구성요소를 사용해야 합니다.
address_components[]
는 이 주소에 적용할 수 있는 별도의 구성요소가 포함된 배열입니다.각 주소 구성요소에는 일반적으로 다음과 같은 필드가 포함됩니다.
types[]
는 주소 구성요소의 유형을 나타내는 배열입니다. 지원되는 유형의 목록을 참고하세요.long_name
은 지오코더에서 반환하는 주소 구성요소의 전체 텍스트 설명 또는 이름입니다.short_name
은 주소 구성요소의 축약된 텍스트 이름입니다(해당하는 경우). 예를 들어 알래스카 주의 주소 구성요소에는long_name
'Alaska'와 두 자리 우편 약어를 사용하는short_name
'AK'가 포함될 수 있습니다.
address_components[]
배열에 대한 다음 사실을 참고하세요.- 주소 구성요소의 배열에
formatted_address
보다 더 많은 구성요소가 포함될 수도 있습니다. formatted_address
에 포함된 것 외에 주소가 포함된 모든 정치적 독립체가 배열에 포함되는 것은 아닙니다. 특정 주소가 포함된 모든 정치적 독립체를 가져오려면 역 지오코딩을 사용하여 주소의 위도/경도를 매개변수로 요청에 전달해야 합니다.- 응답의 형식이 요청 간에 동일하게 유지되지 않을 수도 있습니다. 특히
address_components
의 수는 요청된 주소에 따라 다르며 동일한 주소에 대해서도 시간이 지남에 따라 변경될 수 있습니다. 배열에서 구성요소의 위치가 변경될 수 있습니다. 구성요소의 유형이 변경될 수 있습니다. 특정 구성요소가 이후 응답에서 누락될 수 있습니다.
구성요소 배열을 처리하려면 응답을 구문 분석하고 표현식을 통해 적절한 값을 선택해야 합니다. 답변 파싱 가이드를 참고하세요.
postcode_localities[]
는 우편번호에 포함된 최대 100개의 지역을 나타내는 배열입니다. 이 배열은 우편 번호에 여러 지방이 포함된 결과에만 나타납니다.geometry
에는 다음 정보가 포함됩니다.location
에는 지오코딩된 위도, 경도 값이 포함됩니다. 정상적인 주소 조회의 경우, 일반적으로 이 필드가 가장 중요합니다.location_type
은 지정된 위치에 대한 추가 데이터를 저장합니다. 현재 다음과 같은 값이 지원됩니다."ROOFTOP"
은 반환된 결과가 정확한 지오코드임을 나타내며, 우리는 거리 주소 수준의 정밀도를 가진 정확한 위치 정보를 가지고 있습니다."RANGE_INTERPOLATED"
는 반환된 결과가 일반적으로 도로에서 정확한 두 지점(예: 교차로) 간에 보간된 근사값을 반영함을 나타냅니다. 상세 주소에 옥상 지오코드를 사용할 수 없는 경우 일반적으로 보간된 결과가 반환됩니다."GEOMETRIC_CENTER"
는 반환된 결과가 폴리라인 (예: 거리) 또는 폴리곤 (지역)과 같은 결과의 기하학적 중심임을 나타냅니다."APPROXIMATE"
는 반환된 결과가 근사값임을 나타냅니다.
viewport
는 반환된 결과를 표시하기 위한 권장 뷰포트를 포함하며, 이 뷰포트는 뷰포트 경계 상자의southwest
및northeast
모서리를 정의하는 두 개의 위도,경도 값으로 지정됩니다. 일반적으로 뷰포트는 사용자에게 결과를 표시할 때 프레임을 만드는 데 사용됩니다.- 선택적으로 반환되는
bounds
는 반환된 결과를 완전히 포함할 수 있는 경계 상자를 저장합니다. 참고: 이러한 경계가 권장된 표시 영역과 일치하지 않을 수도 있습니다. (예를 들어 샌프란시스코에는 실질적으로 도시의 일부지만 표시 영역에 반환되면 안 되는 패럴론 섬이 포함됩니다.)
-
plus_code
(Open Location Code 및 Plus Code 참고)는 위도와 경도 좌표에서 파생된 인코딩된 위치 참조로 1/8000도x1/8000도 (적도에서 14mx14m) 이하의 영역을 나타냅니다. Plus Code는 주소가 없는 장소 (건물에 번호가 지정되지 않거나 거리 이름이 없는 장소)의 상세 주소 대신 사용할 수 있습니다. API가 항상 플러스 코드를 반환하는 것은 아닙니다.서비스가 Plus Code를 반환하는 경우 글로벌 코드 및 복합 코드로 형식이 지정됩니다.
global_code
는 4자리 지역 코드와 6자 이상의 로컬 코드(849VCWC8+R9)입니다.compound_code
는 명시적인 위치가 포함된 6자 이상의 로컬 코드(CWC8+R9, Mountain View, CA, USA)입니다. 이 콘텐츠를 프로그래매틱 방식으로 파싱하지 마세요.
-
partial_match
는 지오코더가 원래 요청에 대해 정확히 일치하는 결과를 반환하지 않았지만 요청된 주소의 일부분과 일치함을 나타냅니다. 원래 요청에 맞춤법 오류 또는 불완전한 주소가 포함되어 있는지 검사할 수도 있습니다.부분 일치는 요청에 전달되는 지역 내에 상세 주소가 존재하지 않는 경우 가장 자주 발생합니다. 요청이 동일한 지역에 있는 두 개 이상의 위치와 일치하는 경우에도 부분 일치가 반환될 수 있습니다. 예를 들어 'Hillpar St, Bristol, UK'는 Henry Street 및 Henrietta Street 모두에 대해 부분 일치를 반환합니다. 요청에 맞춤법이 틀린 주소 구성요소가 포함된 경우에는 지오코딩 서비스에서 대체 주소를 제안할 수도 있습니다. 이러한 방식으로 실행된 제안도 부분 일치로 표시될 수 있습니다.
place_id
는 다른 Google API와 함께 사용할 수 있는 고유 식별자입니다. 예를 들어 Places API 요청에서place_id
를 사용하여 전화번호, 영업시간, 사용자 리뷰 등 지역 비즈니스의 세부정보를 가져올 수 있습니다. 장소 ID 개요를 참고하세요.
주소 유형 및 주소 구성요소 유형
결과의 types[]
배열은 주소 유형을 나타냅니다. 주소 유형의 예로는 거리 주소, 국가 또는 정치적 엔터티가 있습니다. address_components[]
에는 주소의 각 부분에 대한 유형을 나타내는 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
는 이름이 지정된 관심 장소를 나타냅니다. 일반적으로 이러한 '관심 장소'는 '엠파이어 스테이트 빌딩' 또는 '에펠탑'과 같이 다른 카테고리에 쉽게 포함되지 않는 유명한 지역 항목입니다.
빈 유형 목록은 예를 들어 프랑스의 리외디와 같이 특정한 주소 요소에 대해 알려진 유형이 없다는 것을 나타냅니다.
위의 유형 외에도 여기에 나열된 유형이 주소 구성요소에 포함될 수 있습니다. 이 목록은 전체 목록이 아니며 변경될 수 있습니다.
floor
는 건물 주소의 층을 나타냅니다.establishment
는 일반적으로 아직 분류되지 않은 장소를 나타냅니다.landmark
는 탐색을 돕기 위해 참조로 사용되는 주변 장소를 나타냅니다.point_of_interest
는 이름이 지정된 관심 장소를 나타냅니다.parking
는 주차장 또는 주차 시설을 나타냅니다.post_box
는 특정 사서함을 나타냅니다.postal_town
은 일부 국가에서 우편 주소에 사용되는locality
및sublocality
와 같은 지리적 영역의 그룹을 나타냅니다.room
은 건물 주소의 방을 나타냅니다.street_number
는 정확한 번지를 나타냅니다.bus_station
,train_station
,transit_station
은 버스, 기차, 대중교통 정류장의 위치를 나타냅니다.
표시 영역 상세 검색
지오코딩 요청에서는 (경계 상자로 표시된) 지정된 뷰포트 내의 결과를 선호하도록 Geocoding 서비스에 지시를 내릴 수 있습니다. 이렇게 하려면 요청 URL 내에서 bounds
매개변수를 설정합니다.
bounds
매개변수는 이 경계 상자의 남서쪽 및 북동쪽 모서리의 위도/경도 좌표를 정의하며, 파이프(|
) 문자를 사용하여 좌표를 구분합니다.
예를 들어 '워싱턴'의 지오코드는 일반적으로 미국 워싱턴주를 반환합니다.
요청:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
응답:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
그러나 미국 북동부 주변의 경계 상자를 정의하는 bounds
인수를 추가하면 이 지오코드는 워싱턴 D.C. 시를 반환합니다.
요청:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
응답:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
지역 편중
지오코딩 요청에서 region
매개변수를 사용하여 특정 지역으로 편중된 결과를 반환하도록 지오코딩 서비스에 지시할 수 있습니다. 이 매개변수는 지역 편중을 지정하는 ccTLD (국가 코드 최상위 도메인) 인수를 취합니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하며, 몇몇 눈에 띄는 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk
)인 반면 ISO 3166-1 코드는 'gb'입니다(기술적으로 'Great Britain과 Northern Ireland 연방국' 엔터티).
주요 Google 지도 애플리케이션이 공식적으로 출시되는 모든 도메인에 대해 지오코딩 결과가 편중될 수 있습니다. 상세 검색은 특정 도메인의 결과만을 선택합니다. 이 도메인 외부에 관련성이 더 높은 결과가 있는 경우 이 결과가 포함될 수도 있습니다.
예를 들어 'Toledo'의 지오코드는 Geocoding API의 기본 도메인이 미국으로 설정되어 있으므로 이 결과를 반환합니다. 요청:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
응답:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
region=es
(스페인)으로 '톨레도'에 대한 지오코딩 요청을 수행하면 스페인 도시를 반환합니다.
요청:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
응답:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
구성요소 필터링
지오코딩 응답에서 Geocoding API는 특정 지역으로 제한된 주소 결과를 반환할 수 있습니다. components
필터를 사용하여 제한을 지정할 수 있습니다. 필터는 파이프 (|
)로 구분된 component:value
쌍의 목록으로 구성됩니다. 필터 값은 다른 지오코딩 요청과 동일한 방식의 맞춤법 교정 및 부분 일치를 지원합니다. 지오코더가 구성요소 필터와 부분적으로 일치하는 항목을 찾으면 응답에 partial_match
필드가 포함됩니다.
필터링할 수 있는 components
는 다음과 같습니다.
postal_code
는postal_code
및postal_code_prefix
와 일치합니다.country
는 국가 이름 또는 두 자리 ISO 3166-1 국가 코드와 일치하는 항목을 찾습니다. API는 국가 정의에 대한 ISO 표준을 따르며 필터링은 해당하는 국가의 ISO 코드를 사용할 때 가장 잘 작동합니다.
다음 components
는 결과에 영향을 주기 위해 사용될 수 있지만 시행되지는 않습니다.
route
는 경로의 긴 이름 또는 짧은 이름과 일치합니다.locality
는locality
및sublocality
유형과 일치합니다.administrative_area
는 모든administrative_area
수준과 일치합니다.
구성요소 필터링에 관한 참고사항:
- 요청에서 이러한 구성요소 필터를 반복하지 마세요. 그러지 않으면 API가
Invalid_request
:country
,postal_code
,route
를 반환합니다. - 요청에 반복되는 구성요소 필터가 포함된 경우 API는 이러한 필터를 OR이 아닌 AND로 평가합니다.
- 결과는 Google 지도와 일치하며, Google 지도에서는 때때로 예기치 않은
ZERO_RESULTS
응답이 발생합니다. 일부 사용 사례에서는 Place Autocomplete를 사용하면 더 나은 결과를 얻을 수 있습니다. 자세한 내용은 이 FAQ를 참고하세요. - 각 주소 구성요소는
address
매개변수 또는components
필터 중 하나에 지정할 수 있으며, 둘 다 지정할 수는 없습니다. 둘 다에 동일한 값을 지정하면ZERO_RESULTS
가 발생할 수 있습니다.
components=country:GB
이 포함된 'High St, Hastings'의 지오코딩은 미국 헤이스팅스온허드슨이 아닌 영국 헤이스팅스의 결과를 반환합니다.
요청:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
응답:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
components=country:ES
를 사용하여 '산타크루스' 지역에 대한 지오코딩 요청을 수행하면 스페인 카나리아 제도의 산타크루스 데 테네리페가 반환됩니다.
요청:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
응답:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
서로를 제외시키는 필터를 제공한 경우에만 구성요소 필터링이 ZERO_RESULTS
응답을 반환합니다.
요청:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
응답:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
components
필터를 사용하면 주소 매개변수 없이도 유효한 쿼리를 실행할 수 있습니다. 전체 주소를 지오코딩할 때 요청에 건물 이름과 번호가 포함된 경우 address
매개변수가 필요합니다.
요청:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
응답:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}