Geocoding

주소정보를 지리적좌표값(위도,경도)으로 변환해주는 API입니다.

이값을 여러가지형태로 표현가능하고, 맵에 표시하거나, 배치할 수도 있습니다.

Google Geocoding API의 경우 (https://developers.google.com/maps/documentation/geocoding/?hl=ko)

대표적으로 쓰이는 API라 할 수 있죠

아래는 Google Geocoding API의 내용입니다.

대상

이 문서는 지도에서 Google Maps API 중 하나에서 제공하는 지도에서 지오코딩 데이터를 사용하려는 웹사이트와 모바일 개발자를 대상으로 합니다. 또한 API 사용 소개 및 사용 가능한 매개변수에 대한 참조 문서도 제공합니다.

이 서비스는 일반적으로 지도에 애플리케이션 콘텐츠를 배치하기 위해 사전에 알려진 정적 주소를 지오코딩하도록 설계된 것이며, 예를 들어 사용자 입력에 실시간으로 응답하기 위한 것은 아닙니다. 동적 지오코딩의 경우(예: 사용자 인터페이스 요소 내) JavaScript API V2 클라이언트 지오코더, JavaScript API V3 클라이언트 지오코더 또는 Maps API for Flash 클라이언트 지오코더에 대한 설명서를 참조하세요.

지오코딩은 시간과 리소스가 많이 소요되는 작업입니다. 가능하면 여기 설명한 Geocoding API나 다른 지오코딩 서비스를 사용하여 주소를 미리 변환하고 결과를 직접 디자인한 임시 캐시에 저장하세요.

사용 제한

Google Geocoding API를 사용하면 하루에 요청할 수 있는 Geolocation에 대한 쿼리가 2,500개로 제한됩니다. Google Maps API Premier 사용자는 하루에 최대 100,000개의 요청을 수행할 수 있습니다. 이 한도는 Geocoding API의 남용 및/또는 용도 변경을 방지하기 위한 것으로 향후 예고 없이 변경될 수 있습니다. 또한 서비스의 남용을 막기 위해 요청 속도 제한도 적용합니다. 24시간 제한을 초과하거나 다른 방법으로 서비스를 악용하는 경우 Geocoding API가 일시적으로 작동하지 않을 수 있습니다. 이 제한을 계속 초과하면 Geocoding API에 대한 액세스가 차단될 수 있습니다.

참고: Geocoding API는 Google 지도에서만 사용되며 지도 위에 결과가 표시되지 않는 지오코딩은 사용할 수 없습니다. 허용되는 사용에 대한 자세한 내용은 Maps API 이용약관 라이센스 제한을 참조하세요.

지오코딩 요청

Geocoding API 요청 형식은 다음과 같아야 합니다.

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

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

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

HTTPS를 통해 Geocoding API에 액세스하려면 다음을 사용하세요.

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

HTTPS는 요청에 사용자의 위치와 같은 민감한 사용자 데이터를 포함하는 애플리케이션에 사용하는 것이 좋습니다.

이 경우 일부 매개변수는 필수이며 나머지는 선택사항입니다. URL의 표준에 따라 모든 매개변수는 앰퍼샌드(&) 문자로 구분합니다. 매개변수와 가능한 값 목록은 아래에 나와 있습니다.

Geocoding API는 다음 URL 매개변수를 사용하여 지오코딩 요청을 정의합니다.

• address(필수사항) — 지오코딩하려는 주소입니다.*

또는

• latlng(필수사항) — 읽을 수 있는 가장 가까운 주소를 얻기 위한 텍스트 위도/경도 값입니다.*
• bounds(선택사항) — 지오코드 결과를 더 분명하게 바이어스하기 위한 뷰포트의 경계상자입니다. 자세한 내용은 아래의 뷰포트 바이어스를 참조하세요.
• region(선택사항) — ccTLD('최상위 도메인') 두 문자 값으로 지정되는 지역 코드입니다. 자세한 내용은 아래의 지역 바이어스를 참조하세요.
• language(선택사항) — 결과를 반환할 때 사용할 언어입니다. 지원되는 도메인 언어 목록을 참조하세요. 지원되는 언어는 자주 업데이트되므로 이 목록은 완전하지 않을 수 있습니다. language를 지정하지 않으면 지오코더는 요청을 보낸 도메인의 기본 언어를 사용하려고 합니다(가능한 경우).
• sensor(필수사항) - 지오코딩 요청이 위치 센서가 있는 기기에서 나온 것인지 여부를 나타냅니다. 이 값은 true 또는 false여야 합니다.

* 참고: address 또는 latlng를 전달하여 조회할 수 있습니다. latlng를 전달하면 지오코더가 역 지오코드라는 것을 수행합니다. 자세한 내용은 역 지오코딩을 참조하시기 바랍니다.

bounds 및 region 매개변수는 지오코더의 결과에 영향을 줄뿐이고 완전히 구속하지는 않습니다.

지오코딩 응답

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

JSON 출력 형식

이 예에서 Geocoding API는 '1600 Amphitheatre Parkway, Mountain View, CA' 쿼리에 대한 json 응답을 요청합니다.

http://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=true_or_false

이 값을 반드시 명시적으로 true 또는 false로 설정해야 함을 강조하기 위해 이 예에서는 sensor 매개변수를 true_or_false 변수로 남겨두었습니다.

다음은 이 요청에 의해 반환된 JSON입니다. 실제 JSON에는 공백이 더 적을 수 있습니다. 요청 간 공백의 양이나 형식에 대해 가정하지 않아야 합니다.

{
  "status": "OK",
  "results": [ {
    "types": street_address,
    "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    "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": "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
    } ],
    "geometry": {
      "location": {
        "lat": 37.4219720,
        "lng": -122.0841430
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "southwest": {
          "lat": 37.4188244,
          "lng": -122.0872906
        },
        "northeast": {
          "lat": 37.4251196,
          "lng": -122.0809954
        }
      }
    }
  } ]
}

JSON 응답에는 두 가지 루트 요소가 포함됩니다.

• "status"에는 요청에 대한 메타데이터가 포함됩니다. 아래의 상태 코드를 참조하세요.
• "results"에는 지오코딩된 주소 정보와 도형 정보의 배열이 있습니다.

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

결과에서 값을 추출하려면 일반적으로 이러한 결과를 파싱해야 합니다. JSON 파싱은 상대적으로 쉽습니다. 권장되는 디자인 패턴에 대한 자세한 내용은 JSON 파싱을 참조하세요.

XML 출력 형식

이 예에서 Geocoding API는 위와 동일한 '1600 Amphitheatre Parkway, Mountain View, CA' 쿼리에 대해 xml 응답을 요청합니다.

http://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=true_or_false

다음은 이 요청에 의해 반환된 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> 
 </result> 
</GeocodeResponse> 

XML 응답은 한 개의 <GeocodeResponse>와 다음 두 개의 최상위 요소로 구성됩니다.

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

이 응답은 JSON 응답에 비해 상당히 깁니다. 따라서 어떤 이유로든 서비스에 json이 필요하지 않으면 xml을 기본 출력 플래그로 사용하는 것이 좋습니다. 또한 XML 트리를 처리할 때는 올바른 노드와 요소를 참조하도록 주의해야 합니다. 출력 처리에 대한 권장 디자인 패턴에 대한 자세한 내용은 XPath로 XML 파싱하기를 참조하세요.

이 문서의 나머지 부분에서는 JSON 구문을 사용합니다. 대부분의 경우 출력 형식은 문서에서 개념이나 필드 이름을 표시하는 목적과 관계가 없습니다. 그러나 다음과 같은 미묘한 차이가 있습니다.

• XML 결과는 루트 <GeocodeResponse> 요소에 포함됩니다.
• JSON은 여러 요소가 있는 항목을 복수 배열(types)로 나타내지만, XML은 이를 여러 단수 요소(<type>)로 나타냅니다.
• JSON에서는 빈 요소가 빈 배열로 나타나지만, XML에서는 이러한 요소가 누락됩니다. 예를 들어 JSON에서는 결과를 생성하지 않는 응답이 빈 results 배열을 반환하지만, XML에서는 <result> 요소가 누락됩니다.

상태 코드

지오코딩 응답 객체의 "status" 필드에는 요청의 상태가 포함되어 있으며, 지오코딩 서비스의 실패 이유를 사용자가 쉽게 추적하도록 도움을 주는 디버깅 정보가 포함될 수도 있습니다. "status" 필드에는 다음 값이 포함될 수 있습니다.

• "OK"는 오류가 발생하지 않았음을 나타냅니다. 주소가 성공적으로 파싱되었고 최소 한 개의 지오코드가 반환되었습니다.
• "ZERO_RESULTS"는 지오코딩이 성공했지만 반환된 결과가 없음을 나타냅니다. 이는 지오코딩이 존재하지 않는 address 또는 원격 지역의 latlng을 전달한 경우 발생할 수 있습니다.
• "OVER_QUERY_LIMIT"는 할당량을 초과했음을 나타냅니다.
• "REQUEST_DENIED"는 요청이 거부되었음을 나타냅니다. 일반적인 이유는 sensor 매개변수가 없기 때문입니다.
• "INVALID_REQUEST"는 일반적으로 쿼리(address 또는 latlng)가 누락되었음을 나타냅니다.

결과

지오코더가 결과를 반환하면 결과는 (JSON) results 배열 내에 배치됩니다. 주소가 없는 경우와 같이 지오코더에서 반환할 결과가 없는 경우에도 빈 results 배열이 반환됩니다. (XML 응답은 0개 이상의 <result> 요소로 구성됩니다.)

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

• types[] 배열은 반환된 결과의 유형을 나타냅니다. 이 배열은 결과에 반환된 기능의 유형을 나타내는 하나 이상의 태그 집합을 포함합니다. 예를 들어 '시카고'라는 지오코드는 'locality'를 반환하여 '시카고'가 도시임을 나타내며 'political'도 반환하여 정치적 엔티티임을 나타냅니다.

• formatted_address는 이 위치에 대한 읽을 수 있는 주소를 포함하는 문자열입니다. 이 주소는 주로 'postal 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 내에 명시된 것보다 더 많은 주소 구성요소가 포함될 수 있습니다.

• geometry에는 다음 정보가 포함됩니다.

  • location은 지오코딩된 위도와 경도 값을 포함합니다. 일반적인 주소 조회의 경우 대개 이 필드가 가장 중요합니다.

  • location_type는 지정된 위치에 대한 추가 데이터를 저장합니다. 현재 다음 값이 지원됩니다.

    • "ROOFTOP"은 번지 수준까지 정확한 위치 정보를 가지고 있기 때문에 반환된 결과가 정확한 지오코드임을 나타냅니다.
    • "RANGE_INTERPOLATED"는 반환된 결과가 두 정확한 점(예: 교차점) 사이에 삽입(interpolate)된 일반적으로 도로에 대한 근사값을 반영함을 나타냅니다. 삽입(interpolate)된 결과는 일반적으로 옥상 지오코드를 번지수에 사용할 수 없을 때 반환됩니다.
    • "GEOMETRIC_CENTER"는 반환된 결과가 폴리라인(예: 거리) 또는 폴리곤(지역)과 같이 결과의 형상 중심임을 나타냅니다.
    • "APPROXIMATE"는 반환된 결과가 근사치임을 나타냅니다.
  • viewport에는 뷰포트 경계상자의 southwest 및 northeast 모서리를 정의하는 두 개의 위도/경도 값으로 지정된, 반환된 결과를 표시하기 위한 권장 뷰포트가 포함되어 있습니다. 일반적으로 뷰포트는 사용자에게 표시할 때 결과를 프레임에 넣는 데 사용됩니다.
  • 선택적으로 반환되는 bounds는 반환된 결과를 완전히 포함할 수 있는 경계상자를 저장합니다. 이러한 경계는 권장된 뷰포트와 일치하지 않을 수도 있습니다. 예를 들어 샌프란시스코에는 기술적으로 도시에 속해 있지만 뷰포트에 반환되지 않아야 하는Farallon 섬이 포함되어 있습니다.
• partial_match는 지오코더가 원래 요청한 주소와 정확하게 일치하지 않지만 일부 일치하는 주소를 반환했음을 나타냅니다. 맞춤법 오류 및 주소가 완전한지 원래 요청을 확인하는 것이 좋습니다. 부분 일치는 주로 요청에 전달한 지역에 해당 번지수가 존재하지 않는 경우 발생합니다.

Geocoding API 요청에 대한 개별 응답의 정확한 형식이 보장되지 않기 때문에 요소가 절대 위치에 있을 것이라고 가정해서는 안 됩니다. (특히 Geocoding API 응답 내 address_components의 수는 요청된 주소에 따라 달리질 수 있으며 시간이 지남에 따라 변경될 수 있습니다.) 대신 응답을 파싱하고 표현식을 통해 적절한 값을 선택해야 합니다. 자세한 내용은 웹 서비스 응답 파싱하기를 참조하세요.

주소 구성요소 유형

반환된 결과 내 types[] 배열은 주소 유형을 나타냅니다. 이러한 유형이 address_components[] 배열 내에 반환되어 특정 주소 구성요소의 유형을 나타낼 수도 있습니다. 지오코더 내 주소는 여러 유형을 가질 수 있으며 유형은 '태그'로 간주될 수 있습니다. 예를 들어 여러 도시는 political 및 locality 유형으로 태그가 지정됩니다.

지원되는 유형은 다음과 같으며 HTTP 지오코더에 의해 반환됩니다.

• street_address는 정확한 번지수를 나타냅니다.
• route는 이름이 지정된 경로(예: 'US 101')를 나타냅니다.
• intersection은 일반적으로 두 주요 도로의 주요 교차로를 나타냅니다.
• political은 정치적 엔티티를 나타냅니다. 일반적으로 이 유형은 특정 도시 행정구역의 폴리곤을 나타냅니다.
• country는 국가 정치적 엔티티를 나타내고 일반적으로 지오코더에 의해 반환되는 최고 유형입니다.
• administrative_area_level_1은 국가 수준 아래 첫 번째 도시 엔티티를 나타냅니다. 미국 내에서 이러한 행정구역 수준은 주입니다. 모든 국가가 이러한 행정구역 수준을 나타내지는 않습니다.
• administrative_area_level_2는 국가 수준 아래 두 번째 도시 엔티티를 나타냅니다. 미국 내에서 이러한 행정구역 수준은 카운티입니다. 모든 국가가 이러한 행정구역 수준을 나타내지는 않습니다.
• administrative_area_level_3는 국가 수준 아래 세 번째 도시 엔티티를 나타냅니다. 이 유형은 작은 도시 구획을 나타냅니다. 모든 국가가 이러한 행정구역 수준을 나타내지는 않습니다.
• colloquial_area는 엔티티에 일반적으로 사용되는 대체 이름을 나타냅니다.
• locality는 편입된 시/군/구 정치적 엔티티를 나타냅니다.
• sublocality는 locality 아래 첫 번째 도시 엔티티를 나타냅니다.
• neighborhood는 이름이 지정된 인근 지역을 나타냅니다.
• premise는 이름이 지정된 위치, 일반적으로 공통 이름을 가진 건물 또는 여러 건물을 나타냅니다.
• subpremise는 이름이 지정된 위치 아래 첫 번째 엔티티, 일반적으로 공통 이름을 가진 여러 건물 내 한 건물을 나타냅니다.
• postal_code는 국가 내에서 우편을 보낼 때 주소로 사용되는 우편번호를 나타냅니다.
• natural_feature는 특정 자연지물을 나타냅니다.
• airport는 공항을 나타냅니다.
• park는 이름이 지정된 공원을 나타냅니다.
• point_of_interest는 이름이 지정된 관심 장소를 나타냅니다. 일반적으로 'POI'는 '엠파이어 스테이트 빌딩'이나 '자유의 여신상' 같이 다른 카테고리에 쉽게 넣을 수 없는 유명한 현지 지형지물입니다.

위에 나열된 유형 외에도 주소 구성요소는 다음 유형을 나타낼 수 있습니다.

• post_box는 특정 우편함을 나타냅니다.
• street_number는 정확한 번지를 나타냅니다.
• floor는 건물 주소의 층을 나타냅니다.
• room은 건물 주소의 사무실을 나타냅니다.

역 지오코딩(주소 조회)

일반적으로 지오코딩이라는 용어는 읽을 수 있는 주소를 지도 위의 위치로 변환하는 과정을 나타냅니다. 반대로 지도 위의 위치를 읽을 수 있는 주소로 변환하는 과정을 역 지오코딩이라고 합니다.

Geocoding API는 latlng 매개변수를 통해 직접 역 지오코딩을 지원합니다. 예를 들면 다음의 쿼리에는 브룩클린에서 위치의 위도/경도 값이 포함됩니다.

http://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&sensor=true_or_false

참고: latlng 매개변수로 전달할 때 위도 및 경도 값 사이에 공백이 없는지 확인합니다.

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

{
  "status": "OK",
  "results": [ {
    "types": street_address,
    "formatted_address": "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
    "address_components": [ {
      "long_name": "275-291",
      "short_name": "275-291",
      "types": street_number
    }, {
      "long_name": "Bedford Ave",
      "short_name": "Bedford Ave",
      "types": route
    }, {
      "long_name": "New York",
      "short_name": "New York",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "Brooklyn",
      "short_name": "Brooklyn",
      "types": [ "administrative_area_level_3", "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
    } ],
    "geometry": {
      "location": {
        "lat": 40.7142298,
        "lng": -73.9614669
      },
      "location_type": "RANGE_INTERPOLATED",
      "viewport": {
        "southwest": {
          "lat": 40.7110822,
          "lng": -73.9646145
        },
        "northeast": {
          "lat": 40.7173774,
          "lng": -73.9583193
        }
      }
    }
  },
  
  ... Additional results[] ...

역 지오코더는 둘 이상의 결과를 반환합니다. 결과의 "formatted_addresses"는 우편 주소가 아니라 위치를 지리적으로 명명하는 방법입니다. 예를 들어 시카고에 있는 한 점을 지오코딩할 때 지오코딩된 점은 번지, 도시(시카고), 주(일리노이) 또는 국가(미국)로 표시될 수 있습니다. 지오코더에게는 모든 것이 '주소'입니다. 역 지오코더는 이러한 모든 유형을 유효한 결과로 반환합니다.

역 지오코더는 정치적 엔티티(국가, 지방, 도시 및 인근지역), 거리 주소 및 우편 코드와 일치합니다.

이전 쿼리에서 반환된 formatted_address 값의 전체 목록은 아래와 같습니다.

"formatted_address": "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
"formatted_address": "Williamsburg, NY, USA",
"formatted_address": "New York 11211, USA",
"formatted_address": "Kings, New York, USA",
"formatted_address": "Brooklyn, NY, USA",
"formatted_address": "New York, NY, USA",
"formatted_address": "New York, USA",
"formatted_address": "United States"

일반적으로 주소는 정확성이 가장 큰 것에서 가장 작은 것 순으로 반환되기 때문에, 이 경우처럼 좀 더 정확한 주소가 가장 중요한 결과입니다. 여기서는 가장 구체적인 번지수에서 덜 구체적인 정치적 엔티티에 이르기까지 여러 다른 유형의 주소를 반환합니다(예: 인근지역, 도시, 카운티, 주 등). 좀 더 일반적인 주소와 일치시키려면 반환된 Placemark의 "types" 필드를 조사할 수 있습니다. 자세한 내용은 위의 주소 구성요소 유형을 참조하세요.

참고: 역 지오코딩은 추정치입니다. 지오코더는 특정 오차 범위 내 가장 가까운 주소 지정 가능 위치를 찾습니다. 일치하는 위치가 없으면 결과를 반환하지 않습니다.

뷰포트 바이어스

지오코딩 서비스가 지정한 뷰포트 내의 결과를 선호하도록 지시할 수도 있습니다(경계상자로 표현됨). 요청 URL 내에 bounds 매개변수를 설정하여 이렇게 할 수 있습니다. 바이어스는 경계 내의 결과만을 선호하지만, 이 경계 외부에 관련성이 더 높은 결과가 있다면 포함될 수 있습니다.

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

예를 들어 'Winnetka'를 지오코딩하면 다음과 같이 일반적으로 시카고 근교를 반환합니다.

요청:

http://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&sensor=false

응답:

{
  "status": "OK",
  "results": [ {
    "types": [ "locality", "political" ],
    "formatted_address": "Winnetka, IL, USA",
    "address_components": [ {
      "long_name": "Winnetka",
      "short_name": "Winnetka",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "Illinois",
      "short_name": "IL",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "United States",
      "short_name": "US",
      "types": [ "country", "political" ]
    } ],
    "geometry": {
      "location": {
        "lat": 42.1083080,
        "lng": -87.7417070
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 42.0917501,
          "lng": -87.7737218
        },
        "northeast": {
          "lat": 42.1248616,
          "lng": -87.7096922
        }
      },
      "bounds": {
        "southwest": {
          "lat": 42.0885320,
          "lng": -87.7715480
        },
        "northeast": {
          "lat": 42.1284090,
          "lng": -87.7110160
        }
      }
    }
  } ]
}

하지만 bounds 인자를 추가하여 로스앤젤레스의 샌 페르난도 밸리에 대한 경계상자를 정의하면 이 지오코드가 해당 위치에 있는 'Winnetka'라는 인근지역을 반환합니다.

요청:

http://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&sensor=false

응답:

{
  "status": "OK",
  "results": [ {
    "types": [ "sublocality", "political" ],
    "formatted_address": "Winnetka, California, USA",
    "address_components": [ {
      "long_name": "Winnetka",
      "short_name": "Winnetka",
      "types": [ "sublocality", "political" ]
    }, {
      "long_name": "Los Angeles",
      "short_name": "Los Angeles",
      "types": [ "administrative_area_level_3", "political" ]
    }, {
      "long_name": "Los Angeles",
      "short_name": "Los Angeles",
      "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" ]
    } ],
    "geometry": {
      "location": {
        "lat": 34.2131710,
        "lng": -118.5710220
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 34.1947148,
          "lng": -118.6030368
        },
        "northeast": {
          "lat": 34.2316232,
          "lng": -118.5390072
        }
      },
      "bounds": {
        "southwest": {
          "lat": 34.1791050,
          "lng": -118.5883200
        },
        "northeast": {
          "lat": 34.2353090,
          "lng": -118.5534191
        }
      }
    }
  } ]
}

지역 바이어스

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

region 매개변수를 사용하여 Geocoding API에서 특정 지역에 바이어스된 결과를 반환하도록 설정할 수도 있습니다. 이 매개변수는 지역 바이어스를 지정하는 ccTLD(국가코드 최상위 도메인) 인자를 받습니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하지만 일부 특별한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk'(.co.uk)인 반면 ISO 3166-1 코드는 'gb'(기술적으로 '영국 및 북 아일랜드'의 엔티티)입니다.

지오코딩 결과는 주 Google 지도 애플리케이션이 공식적으로 실행되는 모든 도메인에 대해 바이어스될 수 있습니다. 바이어스는 특정 도메인에 대한 결과만을 선호하지만, 이 도메인 외부에 관련성이 더 높은 결과가 있다면 포함될 수 있습니다.

예를 들면 'Toledo'에 대한 지오코드는 Geocoding API의 기본값 도메인이 미국으로 설정되어 있으므로 다음 결과를 반환합니다.

http://maps.googleapis.com/maps/api/geocode/json?address=Toledo&sensor=false
# Returns:
#
{
  "status": "OK",
  "results": [ {
    "types": [ "locality", "political" ],
    "formatted_address": "Toledo, OH, USA",
    "address_components": [ {
      "long_name": "Toledo",
      "short_name": "Toledo",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "Ohio",
      "short_name": "OH",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "United States",
      "short_name": "US",
      "types": [ "country", "political" ]
    } ],
    "geometry": {
      "location": {
        "lat": 41.6529200,
        "lng": -83.5777820
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 41.5861889,
          "lng": -83.7058414
        },
        "northeast": {
          "lat": 41.7195821,
          "lng": -83.4497226
        }
      },
      "bounds": {
        "southwest": {
          "lat": 41.5803170,
          "lng": -83.6947540
        },
        "northeast": {
          "lat": 41.7326310,
          "lng": -83.4545660
        }
      }
    }
  } ]
}

region=es(스페인)으로 'Toledo'를 지오코딩하면 스페인 도시를 반환합니다.

http://maps.googleapis.com/maps/api/geocode/json?address=Toledo&sensor=false&region=es
#
# Returns
#
{
  "status": "OK",
  "results": [ {
    "types": [ "locality", "political" ],
    "formatted_address": "Toledo, España",
    "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": "Castilla-La Mancha",
      "short_name": "CM",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "España",
      "short_name": "ES",
      "types": [ "country", "political" ]
    } ],
    "geometry": {
      "location": {
        "lat": 39.8567775,
        "lng": -4.0244759
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 39.7882200,
          "lng": -4.1525353
        },
        "northeast": {
          "lat": 39.9252666,
          "lng": -3.8964165
        }
      },
      "bounds": {
        "southwest": {
          "lat": 39.8105550,
          "lng": -4.1796354
        },
        "northeast": {
          "lat": 39.9250920,
          "lng": -3.8147915
        }
      }
    }
  } ]
}