모든 준비를 마쳤습니다!

개발을 시작하려면 개발자 문서로 이동하세요.

Google Maps Geocoding API 활성화

개발을 시작하기 위해 Google Developers Console에서 우선적으로 해야 할 일을 몇 가지 소개하겠습니다.

  1. 프로젝트 생성 또는 선택
  2. Google Maps Geocoding API 활성화
  3. 적합한 키 생성
계속

개발자 가이드

이 서비스는 또한 클라이언트측 Google Maps JavaScript API의 일부로 제공되거나 서버측에서 Java Client, Python Client, Go Client 및 Node.js Client for Google Maps Services와 함께 사용됩니다. 참고: 서비스 사용 방법에 상관없이 동일한 사용 제한이 적용됩니다. 허용되는 일일 요청 수는 클라이언트측 쿼리와 서버측 쿼리의 합계로 계산합니다.

지오코딩이란?

지오코딩은 주소(예: "1600 Amphitheatre Parkway, Mountain View, CA")를 지리 좌표(예: 위도 37.423021 및 경도 -122.083739)로 변환하는 프로세스이며, 이 프로세스를 사용하여 마커를 지도에 넣거나 지도를 배치할 수 있습니다.

역지오코딩은 지리 좌표를 사람이 읽을 수 있는 주소로 변환하는 프로세스입니다. Google Maps Geocoding API의 역지오코딩 서비스를 사용하면 지정된 장소 ID에 대한 주소를 찾을 수도 있습니다.

Google Maps Geocoding API는 HTTP 요청을 통해 이들 서비스에 액세스할 수 있는 직접적인 방법을 제공합니다. 다음 예시는 Google Maps JavaScript API를 통해 지오코딩 서비스를 사용하여 기본 기능을 보여줍니다.

요청(구성 요소 필터링 및 뷰포트 편중)을 조정하는 데 사용할 수 있는 추가 옵션과 각 결과에 대한 자세한 내용과 같은 Geocoding API의 추가 기능을 보려면 이 예시를 전체 화면으로 보십시오.

시작하기 전에

이 문서는 Google Maps Geocoding API 웹 서비스에 대해 설명합니다. 이 문서는 Google Maps API 중 하나에서 제공하는 지도 내에서 지오코딩 데이터를 사용하기를 원하는 웹사이트 및 모바일 개발자를 대상으로 합니다.

참고: 일반적으로 이 서비스는 애플리케이션 콘텐츠를 지도에 배치하기 위해 정적(미리 알려진) 주소를 지오코딩하도록 고안되었습니다. 이 서비스는 사용자의 입력에 실시간으로 반응하지는 않습니다. (예를 들어, 사용자 인터페이스 요소 내에서) 동적인 지오코딩을 원할 경우 Google Maps JavaScript API 클라이언트 지오코더 및/또는 Google Play 서비스 Location API에 대한 문서를 참조하세요.

지오코딩은 시간과 리소스가 많이 소모되는 작업입니다. 가능하면 (여기에 설명된 Google Maps Geocoding API 또는 다른 지오코딩 서비스를 사용하여) 알려진 주소를 미리 지오코딩하고, 그 결과를 별도의 임시 캐시에 저장하세요.

Google Maps Geocoding API를 사용하려면 API 키가 필요합니다. Geocoding API 개발을 시작하기 전에 인증 요구사항 API 사용 제한을 검토하세요.

Google Maps Geocoding API 요청 형식

Google Maps Geocoding API 요청의 형식은 다음과 같습니다.

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

여기서 outputFormat은 다음 값 중 하나일 수 있습니다.

  • json(권장): JSON(JavaScript Object Notation) 형식으로 출력을 나타냅니다.
  • xml: XML 형식으로 출력을 나타냅니다.

HTTP를 통해 Google Maps Geocoding API에 액세스하려면, 다음을 사용합니다.

http://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

보안은 중요하므로 특히 사용자 위치와 같은 민감한 사용자 데이터를 요청에 포함하는 애플리케이션의 경우, 가급적 HTTPS를 사용하는 것이 좋습니다. HTTPS 암호화를 사용하면 애플리케이션의 보안이 강화되고 스누핑이나 변조에 대한 저항력도 강화됩니다.

참고: URL은 유효하도록 적절하게 인코딩해야 하며 모든 웹 서비스에 대해 8192자로 제한됩니다. URL을 구성할 때 이 제한을 알아야 합니다. 참고로 브라우저, 프록시 및 서버가 다르면 URL 문자 제한도 다를 수 있습니다.

일부 매개변수는 필수인 반면 일부 매개변수는 선택 사항입니다. URL 표준 형식과 마찬가지로, 매개변수는 앰퍼샌드(&) 문자를 사용하여 구분합니다.

각 요청 유형에 대해 다른 매개변수가 사용되므로, 이 페이지의 나머지 부분에서는 지오코딩역지오코딩에 대해 별도로 설명합니다.

지오코딩(위도/경도 조회)

지오코딩 요청의 필수 매개변수:

  • address — 지오코딩하려는 거리 주소. 이 주소는 해당 국가의 국내 우편 서비스에서 사용되는 형식입니다. 사업체 이름과 부서, 스위트 번호 또는 층 번호와 같은 추가적인 주소 요소는 피해야 합니다. 추가적인 지침은 FAQ를 참조하세요.
         또는
    components — 지오코드를 구하려는 구성 요소 필터. 자세한 내용은 구성 요소 필터링을 참조하세요. address가 제공되는 경우, 구성 요소 필터는 또한 선택적 매개변수로 허용됩니다.
  • key — 애플리케이션의 API 키. 이 키는 할당량 관리를 위해 애플리케이션을 식별합니다. 키 가져오기 방법에 대해 알아봅니다.

    참고: Google Maps API 프리미엄 플랜 고객은 Geocoding 요청에서 API 키를 사용하거나 유효한 클라이언트 ID와 디지털 서명을 사용할 수 있습니다. 자세한 내용은 프리미엄 플랜 고객의 인증 매개변수를 참조하세요.

지오코딩 요청의 선택적 매개변수:

  • bounds — 지오코드 결과를 더욱 명확하게 범위 이내로 편중하는 뷰포트의 경계 상자. 이 매개변수는 지오코더의 결과에 영향만 미치며, 결과를 완전히 제한하지는 않습니다. (자세한 내용은 아래의 뷰포트 편중을 참조하세요.)
  • language — 결과 반환 시 사용되는 언어.
    • 지원되는 언어 목록을 참조하세요. 지원되는 언어는 자주 업데이트되므로 목록이 완전하지 않을 수 있습니다.
    • language를 지정하지 않으면 지오코더는 Accept-Language 헤더에 지정된 기본 언어를 사용하거나 요청을 보낸 도메인의 기본 언어를 사용하려고 시도합니다.
    • 지오코더는 사용자와 현지인이 모두 읽을 수 있는 거리 주소를 제공하려고 최선을 다합니다. 이를 위해 API는 기본 언어를 준수하면서 필요한 경우 사용자가 읽을 수 있는 스크립트로 음차한 현지 언어로 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성 요소는 모두 첫 번째 구성 요소에서 선택한 동일한 언어로 반환됩니다.
    • 기본 언어로 이름을 사용할 수 없는 경우 지오코더는 가장 유사한 일치 항목을 사용합니다.
    • 기본 언어는 API가 반환하려고 선택한 결과 집합과 반환 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 유효하거나 유효하지 않을 수 있는 동의어 또는 거리 유형에 대한 약어와 같이 언어에 따라 다르게 약어를 해석합니다. 예를 들어, utcatér는 헝가리어로 거리에 대한 동의어입니다.
  • region — 지역 코드로, ccTLD("최상위 도메인") 두 문자 값으로 지정됩니다. 이 매개변수는 지오코더의 결과에 영향만 미치며, 결과를 완전히 제한하지는 않습니다. (자세한 내용은 아래의 지역 편중을 참조하세요.)
  • components — 파이프(|)로 구분되는 구성 요소 필터. 각 구성 요소 필터는 component:value 쌍으로 구성되며 지오코더의 결과를 완전히 제한합니다. 자세한 내용은 아래의 구성 요소 필터링을 참조하세요.

지오코딩 응답

지오코딩 응답은 URL 요청 경로 내 output 플래그에서 표시한 형식으로 반환됩니다.

이 예시에서, Google Maps 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 Pkwy",
               "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" ]
            }
         ],
         "formatted_address" : "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.4224764,
               "lng" : -122.0842499
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.4238253802915,
                  "lng" : -122.0829009197085
               },
               "southwest" : {
                  "lat" : 37.4211274197085,
                  "lng" : -122.0855988802915
               }
            }
         },
         "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

참고로, JSON 응답은 다음 두 가지 루트 요소를 포함합니다.

  • "status"는 요청의 메타데이터를 포함합니다. 아래의 상태 코드를 참조하세요.
  • "results"는 지오코딩된 주소 정보와 기하학적 정보의 배열을 포함합니다.

일반적으로, 주소 조회 시에 "results" 배열의 단 한 항목만 반환되지만, 주소 쿼리가 모호한 경우에는 지오코더가 여러 결과를 반환할 수도 있습니다.

참고로, 결과에서 값을 추출하려는 경우에는 이 결과를 종합적으로 구문 분석해야 합니다. JSON 구문 분석은 비교적 쉽습니다. 권장되는 디자인 패턴을 확인하려면 JSON 구문 분석을 참조하세요.

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 Pkwy</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>San Jose</long_name>
   <short_name>San Jose</short_name>
   <type>administrative_area_level_3</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>Santa Clara</long_name>
   <short_name>Santa Clara</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.4217550</lat>
    <lng>-122.0846330</lng>
   </location>
   <location_type>ROOFTOP</location_type>
   <viewport>
    <southwest>
     <lat>37.4188514</lat>
     <lng>-122.0874526</lng>
    </southwest>
    <northeast>
     <lat>37.4251466</lat>
     <lng>-122.0811574</lng>
    </northeast>
   </viewport>
  </geometry>
  <place_id>ChIJ2eUgeAK6j4ARbn5u_wAGqWA</place_id>
 </result>
</GeocodeResponse>

참고로, XML 응답은 단일 <GeocodeResponse> 요소와 2개의 최상위 요소로 구성됩니다.

  • <status>는 요청의 메타데이터를 포함합니다. 아래의 상태 코드를 참조하세요.
  • 0개 이상의<result> 요소가 있으며, 각 요소에는 지오코딩된 주소 정보와 기하학적 정보의 단일 집합이 포함됩니다.

참고로, 이 응답은 JSON 응답보다 상당히 더 깁니다. 이 때문에, 서비스에 xml이 꼭 필요한 경우가 아니라면 json을 기본 출력 플래그로 사용하는 것이 좋습니다. 또한 XML 트리를 처리할 때는 올바른 노드와 요소를 참조하도록 주의해야 합니다. 출력 처리에 권장되는 디자인 패턴을 확인하려면 XPath로 XML 구문 분석을 참조하세요.

이 문서의 나머지 부분에서는 JSON 구문을 사용합니다. 대부분의 경우, 문서에서 개념 또는 필드 이름을 설명하기 위한 경우 출력 형식은 중요치 않습니다. 그러나, 다음과 같은 미세한 차이에 유의하세요.

  • XML 결과는 루트 <GeocodeResponse> 요소에 래핑됩니다.
  • JSON은 여러 개의 요소가 있는 항목을 복수의 배열(types)로 나타내는 반면, XML은 여러 개의 단일 요소(<type>)를 사용하여 항목을 나타냅니다.
  • JSON에서는 빈 요소가 빈 배열로 나타나지만, XML에서는 이러한 요소가 없습니다. 결과를 생성하지 않는 응답은 JSON에서 빈 results 배열을 반환하지만, XML에서는 <result> 요소가 없습니다.

상태 코드

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

  • "OK"는 오류가 발생하지 않았음을 나타냅니다. 주소가 성공적으로 구문 분석되고 하나 이상의 지오코드가 반환되었습니다.
  • "ZERO_RESULTS"는 지오코드가 성공했지만 반환된 결과가 없음을 나타냅니다. 이는 존재하지 않는 address가 지오코더에 전달된 경우 발생할 수 있습니다.
  • "OVER_QUERY_LIMIT"는 할당량이 초과되었음을 나타냅니다.
  • "REQUEST_DENIED"는 요청이 거부되었음을 나타냅니다.
  • "INVALID_REQUEST"는 일반적으로 쿼리(address, components 또는 latlng)가 누락되었음을 나타냅니다.
  • "UNKNOWN_ERROR"는 서버 오류로 인해 요청을 처리할 수 없음을 나타냅니다. 다시 시도하면 요청이 성공할 수도 있습니다.

오류 메시지

지오코더가 OK 이외의 상태 코드를 반환하면, 지오코딩 응답 객체 내에 추가적인 error_message 필드가 있을 수 있습니다. 이 필드에는 지정된 상태 코드가 제시된 이유에 대한 상세정보가 포함됩니다.

참고: 이 필드는 항상 존재하는 것은 아니며 내용이 변경될 수 있습니다.

결과

지오코더가 결과를 반환할 때, (JSON) results 배열 내에 결과를 넣습니다. 지오코더에서 결과를 반환하지 않는 경우에도(예: 주소가 존재하지 않는 경우) 여전히 빈 results 배열을 반환합니다. (XML 응답은 0개 이상의 <results> 요소로 구성됩니다.)

일반적인 결과는 다음과 같은 필드로 구성됩니다.

  • types[] 배열은 반환된 결과의 유형을 나타냅니다. 이 배열에는 결과로 반환되는 기능의 유형을 식별하는 0개 이상의 태그 집합이 포함됩니다. 예를 들어, "시카고"의 지오코드는 "시카고"가 도시임을 나타내는 "locality"를 반환하고, 또한 시카고가 정치적 엔터티임을 나타내는 "political"을 반환합니다.

  • formatted_address는 이 위치의 사람이 읽을 수 있는 주소가 포함된 문자열입니다. 이 주소는 대개 "우편 주소"와 일치하지만 국가마다 다를 수 있습니다. (참고로, 영국과 같은 일부 국가에서는 라이선스 제한으로 인해 실제 우편 주소의 배포를 허용하지 않습니다.) 이 주소는 일반적으로 하나 이상의 주소 구성 요소로 구성됩니다. 예를 들어, '111 8th Avenue, New York, NY'라는 주소는 '111'(번지), '8th Avenue'(도로), 'New York'(시) 및 'NY'(미국의 주)와 같은 개별 주소 구성 요소를 포함합니다. 이러한 주소 구성 요소는 아래에 언급된 추가적인 정보를 포함합니다.

  • address_components[]는 위에 설명된 개별 주소 구성 요소를 포함하는 배열입니다. 각 address_component는 일반적으로 다음 항목을 포함합니다.

    • types[]는 주소 구성 요소의 유형을 나타내는 배열입니다.
    • long_name은 지오코더에 의해 반환되는 전체 텍스트 설명 또는 주소 구성 요소의 이름입니다.
    • short_name은 주소 구성 요소의 텍스트 약칭입니다(해당되는 경우). 예를 들어, 알래스카 주의 주소 구성 요소는 'Alaska'의 long_name과 두 글자의 우편 약자를 사용하는 'AK'의 short_name을 가질 수 있습니다.

    참고로, address_components[]에는 formatted_address 내에 언급된 것보다 더 많은 주소 구성 요소가 포함될 수도 있습니다.

  • postcode_localities[]는 우편 번호에 포함된 모든 지방을 표시하는 배열입니다. 이 배열은 우편 번호에 여러 지방이 포함된 결과에만 나타납니다.
  • geometry는 다음 정보를 포함합니다.

    • location은 지오코딩된 위도,경도 값을 포함합니다. 정상적인 주소 조회의 경우, 일반적으로 이 필드가 가장 중요합니다.
    • location_type은 지정된 위치에 대한 추가적인 데이터를 저장합니다. 현재는 다음과 같은 값이 지원됩니다.

      • "ROOFTOP"은 반환된 결과가 정확한 지오코드임을 나타내며, 우리는 거리 주소 수준의 정밀도를 가진 정확한 위치 정보를 가지고 있습니다.
      • "RANGE_INTERPOLATED"는 반환된 결과가 일반적으로 도로에서 정확한 두 지점(예: 교차로) 간에 보간된 근사값을 반영함을 나타냅니다. 거리 주소에 루프톱 지오코드를 사용할 수 없는 경우에는 일반적으로 보간된 결과가 반환됩니다.
      • "GEOMETRIC_CENTER"는 반환된 결과가 폴리라인(예: 거리) 또는 폴리곤(지역)과 같은 결과의 기하학적 중심임을 나타냅니다.
      • "APPROXIMATE"는 반환된 결과가 근사값임을 나타냅니다.
    • viewport는 반환된 결과를 표시하기 위한 권장 뷰포트를 포함하며, 이 뷰포트는 뷰포트 경계 상자의 southwestnortheast 모서리를 정의하는 두 개의 위도,경도 값으로 지정됩니다. 일반적으로 뷰포트는 사용자에게 결과를 표시할 때 프레임을 만드는 데 사용됩니다.
    • (선택적으로 반환되는) bounds는 반환된 결과를 완전히 포함할 수 있는 경계 상자를 저장합니다. 참고로, 이러한 경계가 권장 뷰포트와 일치하지 않을 수도 있습니다. (예를 들어, 샌프란시스코에는 파랄론 제도가 포함되며 이 제도는 법적으로 도시의 일부분이지만, 아마도 뷰포트에는 반환되지 않을 것입니다.)
  • partial_match는 지오코더가 원래 요청에 대해 정확한 일치를 반환하지 않았으며, 요청된 주소의 일부분만 일치함을 나타냅니다. 원래 요청을 검사하여 맞춤법 오류 및/또는 불완전한 주소를 찾아낼 수 있습니다.

    부분 일치가 가장 자주 발생하는 경우는, 요청으로 전달되는 지역 내에 거리 주소가 존재하지 않는 경우입니다. 또한, 동일한 지역에서 한 요청에 대해 2개 이상의 위치가 일치하는 경우에도 부분 일치가 반환될 수 있습니다. 예를 들어, "21 Henr St, Bristol, UK"는 Henry Street 및 Henrietta Street 모두에 대해 부분 일치를 반환합니다. 참고로, 맞춤법이 틀린 주소 요소가 요청에 포함된 경우에는 지오코딩 서비스에서 대체 주소를 제안할 수도 있습니다. 이러한 방식으로 실행된 제안도 부분 일치로 표시될 수 있습니다.

  • place_id는 다른 Google API에 사용할 수 있는 고유 식별자입니다. 예를 들어, place_idGoogle Places API 요청에 사용하여 전화번호, 개점 시간, 사용자 리뷰 등의 지역 사업체 상세정보를 알아낼 수 있습니다. 장소 ID 개요를 참조하세요.

Google Maps Geocoding API 요청에 대한 개별 응답의 형식이 정확하지 않을 수도 있으므로, 해당 요소가 완전히 정확한 위치에 있다고는 가정하지 마십시오. (특히, Geocoding API 응답 내의 address_components 수는 요청된 주소에 따라 달라지며 시간이 지남에 따라 바뀔 수 있습니다.) 그 대신, 을 통해 응답을 구문 분석하고 적절한 값을 선택해야 합니다. 자세한 내용은 웹 서비스 응답 구문 분석을 참조하세요.

주소 유형 및 주소 구성 요소 유형

결과의 types[] 배열은 주소 유형을 나타냅니다. 주소 유형의 예로는 거리 주소, 국가 또는 정치적 엔터티가 있습니다. 또한 address_components[]에 있는 types[] 배열은 주소의 각 부분에 대한 유형을 나타냅니다. 예에는 번지 또는 국가가 포함됩니다. (아래는 유형의 전체 목록입니다.) 주소에는 여러 유형이 있을 수 있습니다. 유형은 '태그'로 간주될 수도 있습니다. 예를 들어, 많은 도시에는 politicallocality 유형의 태그가 붙습니다.

다음 유형들은 주소 유형 및 주소 구성 요소 유형 배열 모두에서 지오코더에 의해 지원되고 반환됩니다.

  • street_address는 정확한 거리 주소를 나타냅니다.
  • route는 이름이 지정된 도로(예: "US 101")를 나타냅니다.
  • intersection은 일반적으로 두 주요 도로가 만나는 주요 교차로를 나타냅니다.
  • political은 정치적 엔터티를 나타냅니다. 일반적으로 이 유형은 일부 정부 행정 구역의 폴리곤을 나타냅니다.
  • country는 전국적인 정치적 엔터티를 나타내며, 일반적으로 Geocoder에서 반환되는 최고 순위의 유형입니다.
  • administrative_area_level_1은 국가 레벨 아래의 1순위 정부 엔터티를 나타냅니다. 미국 내에서, 이러한 행정 레벨은 주입니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다. 대부분의 경우 administrative_area_level_1 짧은 이름은 ISO 3166-2 구획이나 기타 널리 보급된 목록들과 거의 일치하지만, 저희 지오코딩 결과는 다양한 신호와 위치 데이터를 기반으로 하기 때문에 이러한 일치가 보장되지는 않습니다.
  • administrative_area_level_2는 국가 레벨 아래의 2순위 정부 엔터티를 나타냅니다. 미국 내에서, 이러한 행정 레벨은 카운티입니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
  • administrative_area_level_3은 국가 레벨 아래의 3순위 정부 엔터티를 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
  • administrative_area_level_4는 국가 레벨 아래의 4순위 정부 엔터티를 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
  • administrative_area_level_5는 국가 레벨 아래의 5순위 정부 엔터티를 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
  • colloquial_area는 엔터티에 대해 보편적으로 사용되는 대체 이름을 나타냅니다.
  • locality는 시 또는 타운의 병합된 정치적 엔터티를 나타냅니다.
  • ward는 특정한 유형의 일본 지방을 나타내며, 일본 주소 내의 여러 지방 요소를 쉽게 구분해 줍니다.
  • sublocality는 지방 아래의 1순위 정부 엔터티를 나타냅니다. 일부 위치의 경우 다음과 같은 추가적인 유형 중 하나를 수신할 수도 있습니다: sublocality_level_1 ~ sublocality_level_5. 각 하위 지방 레벨은 하나의 정부 엔터티입니다. 숫자가 클수록 더 작은 지역을 나타냅니다.
  • neighborhood는 이름이 지정된 근방을 나타냅니다.
  • premise는 이름이 지정된 위치를 나타내며, 일반적으로 한 건물 또는 공통 이름을 가진 건물 집합을 나타냅니다.
  • subpremise는 이름이 지정된 위치 아래의 1순위 엔터티를 나타내며, 일반적으로 공통 이름을 가진 건물 집합 내의 단일 건물을 나타냅니다.
  • postal_code는 국가 내의 우편물을 처리하는 데 사용되는 우편 번호를 나타냅니다.
  • natural_feature는 유명한 자연 지형을 나타냅니다.
  • airport는 공항을 나타냅니다.
  • park는 이름이 지정된 공원을 나타냅니다.
  • point_of_interest는 이름이 지정된 관심 지점을 나타냅니다. 일반적으로, 이러한 "POI"는 다른 범주에는 잘 맞지 않는 그 지역만의 유명한 엔터티들입니다(예: "엠파이어스테이트 빌딩" 또는 "자유의 여신상").

유형 목록이 비어 있는 것은, 가령 프랑스의 리외디(Lieu-Dit)와 같이 특정 주소 요소에 대한 알려진 유형이 없음을 나타냅니다.

위의 유형들 이외에도, 아래의 유형들이 주소 구성 요소에 포함될 수 있습니다.

참고: 이 목록은 완전하지 않으며 변경될 수 있습니다.

  • floor는 건물 주소의 층을 나타냅니다.
  • 일반적으로 establishment는 아직 분류되지 않은 장소를 나타냅니다.
  • point_of_interest는 이름이 지정된 관심 지점을 나타냅니다.
  • parking은 주차 구역 또는 주차 시설을 나타냅니다.
  • post_box는 특정한 사서함을 나타냅니다.
  • postal_town는 일부 국가에서 우편 주소에 사용되는 지리 지역의 그룹을 나타냅니다(예: localitysublocality).
  • room은 건물 주소의 방을 나타냅니다.
  • street_number는 정확한 번지를 나타냅니다.
  • bus_station, train_stationtransit_station은 버스, 기차 또는 대중교통 정류장의 위치를 나타냅니다.

뷰포트 편중

지오코딩 요청에서는 (경계 상자로 표시된) 지정된 뷰포트 내의 결과를 선호하도록 Geocoding 서비스에 지시를 내릴 수 있습니다. 그렇게 하려면 요청 URL 내에서 bounds 매개변수를 설정합니다. 참고로, 편중은 경계 내의 결과를 선호할 뿐이며, 더 많은 관련 결과가 경계 밖에 있으면 이러한 결과도 포함될 수 있습니다.

bounds 매개변수는 이 경계 상자의 남서쪽 및 북동쪽 모서리의 위도/경도 좌표를 정의하며, 파이프(|) 문자를 사용하여 좌표를 구분합니다.

예를 들어, "위네카"에 대한 지오코드는 일반적으로 시카고의 교외를 반환합니다.

요청:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&key=YOUR_API_KEY

응답:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "New Trier",
               "short_name" : "New Trier",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Cook County",
               "short_name" : "Cook County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Illinois",
               "short_name" : "IL",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, IL, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            },
            "location" : {
               "lat" : 42.10808340000001,
               "lng" : -87.735895
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            }
         },
         "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

그러나, 로스앤젤레스의 샌 페르난도 밸리에 대한 경계 상자를 정의하는 bounds 인수를 추가하면, 이 지오코드는 해당 위치에서 "위네카"라는 근방을 반환합니다.

요청:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

응답:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Los Angeles",
               "short_name" : "LA",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Los Angeles County",
               "short_name" : "Los Angeles 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" ]
            }
         ],
         "formatted_address" : "Winnetka, Los Angeles, CA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            },
            "location" : {
               "lat" : 34.2048586,
               "lng" : -118.5739621
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            }
         },
         "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ",
         "types" : [ "neighborhood", "political" ]
      }
   ],
   "status" : "OK"
}

지역 편중

지오코딩 응답에서, Google Maps Geocoding API는 요청을 보낸 지역(일반적으로 국가)의 영향을 받은 주소 결과를 반환합니다. 예를 들어, 요청이 스페인의 도메인에서 보낸 것이 아니라 미국의 도메인에서 보낸 경우, "샌프란시스코"를 검색하면 다른 결과가 반환될 수도 있습니다.

region 매개변수를 사용하여 특정 지역으로 편중된 결과를 반환하도록 Google Maps Geocoding API를 설정할 수 있습니다. 이 매개변수는 ccTLD(국가 코드 최상위 도메인) 인수를 통해 지역 편중을 지정합니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하며, 몇몇 눈에 띄는 예외가 있습니다. 예를 들어, 영국의 ccTLD는 "uk"(.co.uk)인 반면 ISO 3166-1 코드는 "gb"입니다(기술적으로 Great Britain과 Northern Ireland 연방국" 엔터티).

주요 Google 지도 애플리케이션이 공식적으로 출시되는 모든 도메인에 대해 지오코딩 결과가 편중될 수 있습니다. 참고로, 편중은 특정 도메인의 결과를 선호할 뿐이며, 더 많은 관련 결과가 도메인 밖에 있으면 이러한 결과도 포함될 수 있습니다.

예를 들어, Google Maps 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.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lincoln County",
               "short_name" : "Lincoln County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Oregon",
               "short_name" : "OR",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OR, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            },
            "location" : {
               "lat" : 44.621507,
               "lng" : -123.9384478
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            }
         },
         "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Tama County",
               "short_name" : "Tama County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Iowa",
               "short_name" : "IA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, IA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            },
            "location" : {
               "lat" : 41.9972134,
               "lng" : -92.5835266
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            }
         },
         "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lewis County",
               "short_name" : "Lewis County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "98591",
               "short_name" : "98591",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Toledo, WA 98591, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            },
            "location" : {
               "lat" : 46.4398305,
               "lng" : -122.846783
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            }
         },
         "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

region=es(스페인)으로 "톨레도"에 대한 지오코딩 요청을 수행하면 스페인 도시를 반환합니다. 요청:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

응답:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Vega de Toledo",
               "short_name" : "Vega de Toledo",
               "types" : [ "administrative_area_level_3", "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, Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

구성 요소 필터링

지오코딩 응답에서, Google Maps Geocoding API는 특정 지역으로 제한된 주소 결과를 반환할 수 있습니다. 이 제한은 components 필터를 사용하여 지정됩니다. 필터는 파이프(|)로 구분된 component:value 쌍의 목록으로 구성됩니다. 모든 필터와 일치하는 결과만 반환됩니다. 필터 값은 다른 지오코딩 요청과 동일한 방식의 맞춤법 교정 및 부분 일치를 지원합니다. 구성 요소 필터에 대한 지오코딩 결과가 부분 일치인 경우, 응답에 partial_match 필드가 포함됩니다.

필터링될 수 있는 components는 다음과 같습니다.

  • 경로의 긴 이름 또는 짧은 이름과 일치하는 route.
  • localitysublocality 유형 모두에 대해 일치하는 locality.
  • 모든 administrative_area 레벨과 일치하는 administrative_area.
  • postal_codepostal_code_prefix와 일치하는 postal_code.
  • 국가 이름 또는 두 글자 ISO 3166-1 국가 코드와 일치하는 country.

    참고:국가의 해당 ISO 코드를 사용할 때 필터링이 가장 잘 작동하도록 국가 정의에 대한 ISO 표준을 따릅니다.

참고: 각 주소 구성 요소는 주소 매개변수에만 지정되거나 구성 요소 필터로만 지정될 수 있으며, 둘 모두로 지정될 수는 없습니다. 그럴 경우 ZERO_RESULTS가 발생할 수 있습니다.

components=country:ES로 "산타크루스"에 대한 지오코드는 스페인 카나리아 제도의 산타크루스 데 테네리페를 반환합니다. 요청:

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=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" : "Santa Cruz de Tenerife",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Anaga",
               "short_name" : "Anaga",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canarias",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, 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"
}

구성 요소 필터를 포함하는 쿼리는 필터와 일치하는 지오코딩 결과만을 반환합니다. 일치하는 내용이 없으면, 지오코더는 필터 자체와 일치하는 결과를 반환합니다. 요청:

https://maps.googleapis.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&key=YOUR_API_KEY

응답:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Texas",
               "short_name" : "TX",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Texas, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 36.5007041,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            },
            "location" : {
               "lat" : 31.9685988,
               "lng" : -99.9018131
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 36.5015087,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY",
         "types" : [ "administrative_area_level_1", "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 필터를 사용하면, 주소 매개변수가 없이도 쿼리를 만들 수 있지만, 값이 없이는 구성 요소를 지정할 수 없습니다. 요청:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

응답:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annegatan",
               "short_name" : "Annegatan",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Annegatan, Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Annevägen",
               "short_name" : "Annevägen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Vanda",
               "short_name" : "Vanda",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "01420",
               "short_name" : "01420",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annevägen, 01420 Vanda, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.3282738,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32564009999999,
                  "lng" : 25.1076474
               }
            },
            "location" : {
               "lat" : 60.3271069,
               "lng" : 25.1118046
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.3283059302915,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32560796970849,
                  "lng" : 25.1076474
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Anneplatsen",
               "short_name" : "Anneplatsen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00100",
               "short_name" : "00100",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.1695664,
                  "lng" : 24.9357125
               },
               "southwest" : {
                  "lat" : 60.168997,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1692741,
               "lng" : 24.9348016
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.17063068029151,
                  "lng" : 24.9362052302915
               },
               "southwest" : {
                  "lat" : 60.1679327197085,
                  "lng" : 24.9335072697085
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

역지오코딩(주소 조회)

일반적으로 지오코딩이라는 용어는 사람이 읽을 수 있는 주소를 지도상의 위치로 변환하는 것을 말합니다. 그 반대로 지도상의 위치를 사람이 읽을 수 있는 주소로 변환하는 프로세스를 역지오코딩이라고 합니다.

역지오코딩 요청의 필수 매개변수:

  • latlng — 사람이 읽을 수 있는 가장 가까운 주소를 가져오려는 위치를 지정하는 위도 및 경도 값입니다.
         또는
    place_id — 사람이 읽을 수 있는 주소를 가져오려는 장소의 ID입니다. 장소 ID는 다른 Google API에 사용할 수 있는 고유 식별자입니다. 예를 들어, Google Maps Roads API에 의해 반환되는 placeID를 사용하면 스냅된 지점의 주소를 가져올 수 있습니다. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참조하세요. 장소 ID는 요청에 API 키 또는 Google Maps API 프리미엄 플랜 클라이언트 ID가 포함된 경우에만 지정될 수 있습니다.
  • key — 애플리케이션의 API 키. 이 키는 할당량 관리를 위해 애플리케이션을 식별합니다. 키 가져오기 방법에 대해 알아봅니다.

    참고: Google Maps API 프리미엄 플랜 고객은 역 Geocoding 요청에서 API 키를 사용하거나 유효한 클라이언트 ID와 디지털 서명을 사용할 수 있습니다. 자세한 내용은 프리미엄 플랜 고객의 인증 매개변수를 참조하세요.

역지오코딩 요청의 선택적 매개변수:

역지오코딩 요청에 포함될 수 있는 선택적 매개변수는 다음과 같습니다.

  • language — 결과 반환 시 사용되는 언어.
    • 지원되는 언어 목록을 참조하세요. 지원되는 언어는 자주 업데이트되므로 목록이 완전하지 않을 수 있습니다.
    • language를 지정하지 않으면 지오코더는 Accept-Language 헤더에 지정된 기본 언어를 사용하거나 요청을 보낸 도메인의 기본 언어를 사용하려고 시도합니다.
    • 지오코더는 사용자와 현지인이 모두 읽을 수 있는 거리 주소를 제공하려고 최선을 다합니다. 이를 위해 API는 기본 언어를 준수하면서 필요한 경우 사용자가 읽을 수 있는 스크립트로 음차한 현지 언어로 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성 요소는 모두 첫 번째 구성 요소에서 선택한 동일한 언어로 반환됩니다.
    • 기본 언어로 이름을 사용할 수 없는 경우 지오코더는 가장 유사한 일치 항목을 사용합니다.
  • result_type — 파이프(|)로 구분되는 하나 이상의 주소 유형. 주소 유형의 예: country, street_address, postal_code. 허용되는 값의 전체 목록은 이 페이지의 주소 유형을 참조하세요. 유형을 지정하면 결과가 이 유형으로 제한됩니다. 여러 유형이 지정된 경우, API가 임의 유형과 일치하는 모든 주소를 반환합니다. 참고: 이 매개변수는 API 키 또는 클라이언트 ID가 포함된 요청에만 사용할 수 있습니다.
  • location_type — 파이프(|)로 구분되는 하나 이상의 위치 유형. 유형을 지정하면 결과가 이 유형으로 제한됩니다. 여러 유형이 지정된 경우, API가 임의 유형과 일치하는 모든 주소를 반환합니다. 참고: 이 매개변수는 API 키 또는 클라이언트 ID가 포함된 요청에만 사용할 수 있습니다. 다음과 같은 값이 지원됩니다:
    • "ROOFTOP"은 정확한 주소로만 결과를 제한하며, 우리는 거리 주소 수준의 정밀도를 가진 정확한 위치 정보를 가지고 있습니다.
    • "RANGE_INTERPOLATED"는 일반적으로 도로에서 정확한 두 지점(예: 교차로) 간에 보간된 근사값을 반영하는 주소로만 결과를 제한합니다. 보간된 범위는 일반적으로 거리 주소에 루프톱 지오코드를 사용할 수 없음을 나타냅니다.
    • "GEOMETRIC_CENTER"는 폴리라인(예: 거리) 또는 폴리곤(예: 지역)과 같은 위치의 기하학적 중심으로만 결과를 제한합니다.
    • "APPROXIMATE"는 근사값으로 특성화된 주소로만 결과를 제한합니다.

result_typelocation_type 제한이 모두 존재하는 경우, API는 result_typelocation_type 제한과 모두 일치하는 결과만을 반환합니다.

위도/경도의 역지오코딩

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

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

참고: latlng 매개변수에 넣어 전달할 때, 위도 및 경도 값 사이에 공백이 없도록 하십시오.

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

{
   "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 results[] ...

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

역지오코더는 정치적 엔터티(국가, 주, 도시 및 근방), 거리 주소 및 우편 번호가 일치하는 항목을 찾습니다.

아래는 이전의 쿼리에 의해 반환되는 formatted_address 값의 전체 목록을 나타냅니다.

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

일반적으로 주소는 가장 구체적인 주소부터 가장 광범위한 주소까지 반환되며, 이 경우처럼 가장 눈에 띄는 결과가 더 정확한 주소입니다. 참고로, 우리는 가장 구체적인 거리 주소에서부터 보다 광범위한 정치적 엔터티(예: 근방, 도시, 국가, 주 등)에 이르기까지 다양한 주소 유형을 반환합니다. 특정 주소 유형의 일치하는 항목을 찾으려면, 유형별로 결과 제한에서 아래의 섹션을 참조하세요.

참고: 역지오코딩은 추정값입니다. 지오코더는 특정한 허용오차 내에서 가장 가까운 주소 위치를 찾으려고 시도합니다. 일치하는 항목이 없으면, 지오코더는 0개의 결과를 반환합니다.

장소 ID의 역지오코딩

다음 쿼리는 브루클린의 한 장소에 대한 장소 ID를 포함합니다.

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA&key=YOUR_API_KEY

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

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Ave",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality_level_1", "sublocality", "political" ]
            },
            {
               "long_name" : "Kings County",
               "short_name" : "Kings County",
               "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 Ave, 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
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

유형별로 제한되는 역지오코딩

다음 예에서는 반환되는 주소를 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 키 또는 클라이언트 ID를 포함하지 않기 때문일 수 있습니다.
  • 일반적으로 "INVALID_REQUEST"는 다음 중 하나를 나타냅니다.
    • 쿼리(address, components 또는 latlng)가 누락되었습니다.
    • 잘못된 result_type 또는 location_type이 지정되었습니다.
  • "UNKNOWN_ERROR"는 서버 오류로 인해 요청을 처리할 수 없음을 나타냅니다. 다시 시도하면 요청이 성공할 수도 있습니다.

sensor 매개변수

이전의 Google Maps API는 애플리케이션이 사용자의 위치 파악을 위해 센서를 사용했는지 여부를 나타내기 위해 sensor 매개변수를 포함하도록 요구했습니다. 이 매개변수는 더 이상 필요하지 않습니다.

다음에 대한 의견 보내기...

Google Maps Geocoding API
Google Maps Geocoding API
도움이 필요하시나요? 지원 페이지를 방문하세요.