요청
Geocoding API 요청의 형식은 다음과 같습니다.
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
여기서 outputFormat는 다음 값 중 하나일 수 있습니다.
json(권장)은 출력을 JavaScript Object Notation (JSON) 형식으로 나타냅니다. 또는xml는 XML 형식으로 출력을 나타냅니다.
HTTPS는 필수 항목입니다.
일부 매개변수는 필수인 반면 일부 매개변수는 선택 사항입니다. URL의 표준에 따라
매개변수는 앰퍼샌드 (&) 문자를 사용하여 구분합니다.
이 페이지의 나머지 부분에서는 지오코딩과 역 지오코딩은 별도로 실행됩니다. 각 요청 유형별로 사용할 수 있는 다양한 매개변수가 있습니다.
지오코딩 (위도/경도 조회) 매개변수
지오코딩 요청의 필수 매개변수:
address— 상세 주소 또는 Plus Code 선택해야 합니다. 형식에 따라 주소 지정 해당 국가의 우편 서비스에서 사용됩니다. 추가 업체 이름, 부서, 호수, 층 번호 등의 주소 요소 피해야 합니다 상세 주소 요소는 공백으로 구분해야 합니다. (여기서는%20로 URL 이스케이프 처리된 것으로 표시됨):address=24%20Sussex%20Drive%20Ottawa%20ON
여기 표시된 대로 Plus Code의 형식을 지정합니다. 더하기 기호는%2B로 URL 이스케이프 처리되고 공백은%20로 URL 이스케이프 처리됩니다. <ph type="x-smartling-placeholder">- </ph>
- 글로벌 코드는 4자리 지역 코드이며 6자 이상입니다.
(849VCWC8+R9는
849VCWC8%2BR9)로 설정합니다. - 복합 코드는 6자 이상의 로컬 코드입니다.
명시적인 위치 (CWC8+R9 Mountain View, CA, USA는
CWC8%2BR9%20Mountain%20View%20CA%20USA)를 사용합니다.
--OR--
components: 요소가 있는 구성요소 필터 파이프 (|)로 구분됩니다. 구성요소 필터도 허용됩니다.address가 제공된 경우 선택적 매개변수로 사용됩니다. 구성요소 필터의 각 요소는component:value페어링하고 결과를 완전히 제한합니다. 지오코더에서 가져옵니다. 다음에 대해 자세히 알아보기 구성요소 필터링을 참조하세요.- 글로벌 코드는 4자리 지역 코드이며 6자 이상입니다.
(849VCWC8+R9는
key- 애플리케이션의 API 키입니다. 이 키는 할당량을 관리할 수 있습니다 자세히 알아보기 키 가져오기:
자주 묻는 질문(FAQ)에서 추가 안내를 참조하세요.
지오코딩 요청의 선택적 매개변수:
bounds- 표시 영역의 경계 상자 를 사용하면 지오코드 결과를 더욱 두드러지게 할 수 있습니다. 이 매개변수는 지오코더의 결과에 영향을 미칠 뿐, 결과를 완전히 제한하지는 않습니다. (자세한 내용은 자세한 내용은 아래의 표시 영역 상세 검색을 참조하세요.language- 결과를 반환합니다.- 지원되는 언어를 참조하세요. Google은 지원되는 언어를 자주 업데이트하므로 목록은 일부일 수 있습니다.
language가 제공되지 않으면 지오코더는 기본 언어를 사용합니다.Accept-Language헤더 또는 요청을 보낸 도메인 이름입니다.- 지오코더는 사용자와 로컬 모두가 읽을 수 있어야 합니다. 이 목표를 달성하기 위해 는 선호하는 있습니다. 다른 모든 주소는 기본 있습니다. 주소 구성 요소는 모두 같은 언어로 반환되기 때문에 첫 번째 구성 요소에서 선택됩니다.
- 기본 언어로 이름을 사용할 수 없는 경우 지오코더는 가장 근접한 결과를 표시합니다.
- 선호 언어는 사용자가 선호하는 결과 세트에 약간의 영향을 미칩니다. API가 반환하기로 선택한 값과 반환되는 순서를 지정합니다. 지오코더는 각 특성에 따라 약어를 동의어, 예를 들어 도로 유형의 약어나 한 언어에서는 유효하지만 다른 언어에서는 유효하지 않아야 합니다. 예를 들면 utca입니다. tér는 각각 거리와 광장의 동의어입니다. 헝가리어입니다.
region- ccTLD로 지정된 지역 코드입니다. ('최상위 도메인') 2 문자 값입니다. 이 매개변수는 영향을 주지만 결과를 완전히 제한하지는 않습니다. (자세한 내용은 자세한 내용은 아래의 지역 상세 검색을 참조하세요. 이 매개변수는 관련 법률에 따라 결과에 영향을 미칠 수 있습니다.components- 요소가 있는 구성요소 필터 파이프 (|)로 구분됩니다. 구성요소 필터는 요청에address가 포함되지 않은 경우 필수입니다. 구성요소 필터의 각 요소는component:value페어링하고 결과를 완전히 제한합니다. 지오코더에서 가져옵니다. 다음에 대해 자세히 알아보기 구성요소 필터링을 참조하세요.extra_computations— 이 매개변수를 사용하여 응답에서 다음과 같은 추가 기능이 제공됩니다.ADDRESS_DESCRIPTORS— 다음을 참조하세요. 주소 설명자를 참조하세요.BUILDING_AND_ENTRANCES— 다음을 참조하세요. 출입구 및 건물 외곽선을 참고하세요.
extra_computations매개변수 예를 들면 다음과 같습니다.extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
대답
지오코딩 응답은 output 플래그에서 지정한 형식으로 반환됩니다.
JSON 형식으로 표시할 수 있습니다.
이 예에서 Geocoding API는 json
'서울특별시 강남구 테헤란로 152 강남파이낸스센터 22층'
CA').
이 요청은 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 응답보다 상당히 깁니다. 대상
따라서 json를
어떤 이유로든 서비스에 xml가 필요한 경우가 아니라면 출력 플래그를 지정합니다.
또한 XML 트리를 처리할 때는 주의해야 하므로
올바른 노드와 요소를 찾는 것입니다 자세한 내용은
<ph type="x-smartling-placeholder"></ph>
출력 처리에 권장되는 일부 디자인 패턴을 위해 XPath로 XML 파싱하기
- XML 결과는 루트
<GeocodeResponse>요소에 래핑됩니다. - JSON은 여러 요소가 있는 항목을 복수 배열 (
types)로 나타냅니다. XML은 여러 단수 요소 (<type>)를 사용하여 이를 나타냅니다. - JSON에서 빈 요소는 빈 배열로 표시되지만,
XML에서 이러한 요소를
사용할 수 있습니다 결과를 생성하지 않는 응답은
JSON의
results배열이지만 XML의<result>요소가 없음 예로 들 수 있습니다.
상태 코드
지오코딩 응답 객체의 "status" 필드에는 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> elements.)
일반적인 결과에는 다음 필드가 포함됩니다.
types[]배열은 반환되는 표시됩니다. 이 배열에는 특성이 반환됩니다. 예를 들어 '시카고'의 지오코드 반품 '지역' 이는 '시카고'라는 는 도시이며 '정치'를 반환합니다. 이는 정치적 독립체임을 나타냅니다. 구성요소에 빈 유형이 있을 수 있음 해당 주소 구성요소에 대해 알려진 유형이 없는 경우 배열됩니다. 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의 수는 요청된 주소에 따라 다르며 동일한 주소에 대해서도 시간이 지남에 따라 변경될 수 있습니다. 배열에서 구성요소의 위치가 변경될 수 있습니다. 구성요소의 유형이 변경될 수 있습니다. 특정 구성요소가 이후 응답에서 누락될 수 있습니다.
구성요소 배열을 처리하려면 응답을 파싱해야 합니다. 표현식을 통해 적절한 값을 선택할 수 있습니다. 다음 가이드를 참고하세요. <ph type="x-smartling-placeholder"></ph> 응답 파싱하기
postcode_localities[]는 최대 100개의 지역을 나타내는 배열입니다. 우편번호에 포함됩니다. 결과가 우편인 경우에만 표시됩니다. 여러 지역이 포함된 코드를 뜻합니다geometry에는 다음 정보가 포함됩니다.location에는 지오코딩된 위도와 경도 값이 포함됩니다. 일반 주소 조회의 경우 이 필드가 일반적으로 가장 중요합니다.location_type는 지정된 위치에 대한 추가 데이터를 저장합니다. 이 현재 다음 값이 지원됩니다."ROOFTOP"는 반환된 결과가 다음에 대한 정확한 지오코드임을 나타냅니다. 상세 주소 정밀도까지 정확한 위치 정보를 가지고 있습니다."RANGE_INTERPOLATED"의 의미 반환된 결과가 두 정확한 점 (예: 교차로) 간에 보간된 근사값 (일반적으로 도로에서) 보간된 결과는 일반적으로 거리에서 옥상 지오코드를 사용할 수 없을 때 반환됩니다. 있습니다."GEOMETRIC_CENTER"는 다음을 나타냅니다. 반환된 결과는 다중선 (예: 거리) 또는 다각형 (지역)과 같은 결과"APPROXIMATE"는 반환된 결과는 근사치입니다.
viewport에는 표시에 권장되는 표시 영역이 포함되어 있습니다. 를 정의하는 두 개의 위도/경도 값으로 지정된, 반환된 결과southwest및 표시 영역 경계 상자의northeast모서리 일반적으로 표시 영역은 사용자에게 표시할 때 결과를 프레임에 표시하는 데 사용됩니다.- 선택적으로 반환되는
bounds는 경계 상자를 저장합니다. 반환된 결과를 완전히 포함할 수 있습니다. 이 경계는 지정할 수 있습니다. 예를 들어 샌프란시스코에는 패럴론 군도 은 엄밀히 말하면 도시의 일부이지만 표시 영역에 반환되면 안 될 수 있습니다.)
-
plus_code( 위치 코드 열기 및 plus 코드)는 위도와 경도 좌표에서 파생된 위치 참조로서 면적은 도의 1/8000 x 1/8000 (약 14m x 도)으로 적도에서 14m) 이하입니다. 플러스 코드는 주소가 존재하지 않는 곳 (건물이 없는 곳)의 상세 주소 도로의 이름은 지정되지 않음). API가 항상 플러스 코드를 반환하는 것은 아닙니다.서비스에서 플러스 코드를 반환하면 다음과 같이 전역 코드 및 복합 코드로 형식이 지정됩니다.
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와 함께 사용할 수 있습니다. 예를 들어place_id를 Places API 가져오기 요청 전화번호, 영업시간, 사용자 등 지역 비즈니스의 세부정보 확인할 수 있습니다. 장소 ID 보기 개요를 참조하세요.
주소 유형 및 주소 구성요소 유형
결과의 types[] 배열은
주소 유형일 수 있습니다. 주소 유형의 예로는 상세 주소,
국가 또는 정치적 독립체입니다. types[] 배열은
address_components[]: 각 부분의 유형을 나타냅니다.
있습니다. 예에는 번지 또는 국가가 포함됩니다. (아래는 Ad Exchange의
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은 버스, 기차, 대중교통 정류장의 위치를 나타냅니다.
표시 영역 상세 검색
지오코딩 요청에서는 지오코딩 서비스가
지정된 표시 영역 내 결과 (경계 상자로 표현됨)를 반환합니다. 그러면
요청 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'
(기술적으로 "영국 및 영국"
북아일랜드').
지오코딩 결과는 주 도메인이 있는 모든 도메인에 대해 Google 지도 애플리케이션이 공식적으로 출시되었습니다. 참고로 편향은 특정 도메인의 결과를 선호하는 경우 더 관련성 높은 결과가 있는 경우 이 도메인 외부에도 포함될 수 있습니다.
예를 들어 '톨레도'의 지오코드입니다. 는 이 결과를 반환합니다. 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 코드입니다.
다음 components는 결과에 영향을 주는 데 사용될 수 있지만 사용되지는 않습니다.
시행:
route는 경로의 긴 이름 또는 짧은 이름과 일치하는 항목을 찾습니다.locality상대로locality및sublocality유형.administrative_area이(가) 모든 등급administrative_area개
구성요소 필터링에 대한 참고사항:
- 요청에서 이러한 구성요소 필터를 반복하지 마세요. 이러한 구성요소 필터를 사용하면 API가
Invalid_request:country,postal_coderoute - 요청에 반복되는 구성요소 필터가 포함된 경우 API는 필터를 OR이 아닌 AND로 사용해야 합니다.
- 결과는 Google 지도와 일치하며, 때때로
예상치 못한
ZERO_RESULTS응답이 있습니다. Place Autocomplete 사용 일부 사용 사례에서 더 나은 결과를 제공할 수 있습니다. 자세한 내용은 이 FAQ를 참조하세요. - 각 주소 구성요소의 경우
address에서 지정합니다. 매개변수 또는components필터 중 하나로 지정해야 합니다. 두 값이 같으면ZERO_RESULTS이 될 수 있습니다.
'High St, Hastings'에 대한 지오코드 components=country:GB님과 공유
는 미국 헤이스팅스온허드슨이 아닌 영국 헤이스팅스의 결과를 반환합니다.
요청:
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"
}