지오코딩 서비스

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

개요

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

역 지오코딩은 지리 좌표를 사람이 읽을 수 있는 주소로 변환하는 프로세스입니다(역 지오코딩 (주소 조회) 참고).

지오코더를 사용하여 특정 장소 ID의 주소를 찾을 수도 있습니다.

Maps JavaScript API는 사용자 입력에서 지오코딩과 역 지오코딩을 동적으로 위한 Geocoder 클래스를 제공합니다. 알려진 고정 주소를 지오코딩하려면 지오코딩 웹 서비스를 참고하세요.

시작하기

Maps JavaScript API에서 지오코딩 서비스를 사용하기 전에 먼저 Maps JavaScript API에 설정한 같은 프로젝트의 Google Cloud Console에서 Geocoding API가 사용 설정되어 있는지 확인합니다.

활성화된 API 목록을 보려면:

  1. Google Cloud Console로 이동합니다.
  2. 프로젝트 선택 버튼을 클릭한 후 Maps JavaScript API에 설정한 것과 동일한 프로젝트를 선택하고 열기를 클릭합니다.
  3. 대시보드의 API 목록에서 Geocoding API를 찾습니다.
  4. 목록에 API가 표시되면 준비가 다 된 것입니다. API가 표시되지 않으면 사용 설정합니다.
    1. 페이지 상단에서 API 사용 설정을 선택하여 라이브러리 탭을 표시합니다. 또는 왼쪽 사이드 메뉴에서 라이브러리를 선택합니다.
    2. Geocoding API를 검색한 후 결과 목록에서 선택합니다.
    3. 사용 설정을 선택합니다. 프로세스가 완료되면 Geocoding API대시보드의 API 목록에 표시됩니다.

가격 및 정책

가격 정보

2018년 7월 16일부터 지도, 경로, 장소에 사용한 만큼만 지불하는 새로운 요금제가 도입되었습니다. 자바스크립트 지오코딩 서비스 사용에 대한 새로운 가격 및 사용량 한도에 관한 자세한 내용은 Geocoding API의 사용량 및 결제를 참고하세요.

비율 한도

추가 요청의 비율 한도에 관한 다음 사항에 유의하세요.

동일한 프로젝트를 공유하는 사용자 수에 상관없이 사용자 세션당 추가 비율 제한이 적용됩니다. API를 처음 로드하면 요청의 초기 할당량이 할당됩니다. 이 할당량을 사용하면 API가 초당 추가 요청에 비율 제한을 적용합니다. 특정 기간 내에 너무 많은 요청이 발생하면 API는 OVER_QUERY_LIMIT 응답 코드를 반환합니다.

세션당 속도 제한은 일괄 지오코딩과 같은 일괄 요청에 클라이언트 측 서비스를 사용하지 못하게 합니다. 일괄 요청의 경우 Geocoding API 웹 서비스를 사용합니다.

정책

Geocoding 서비스 사용은 Geocoding API에 관해 설명된 정책을 준수해야 합니다.

지오코딩 요청

Google Maps API는 외부 서버를 호출해야 하므로 지오코딩 서비스 액세스는 비동기식입니다. 따라서 요청 완료 시 실행할 콜백 메서드를 전달해야 합니다. 이 콜백 메서드가 결과를 처리합니다. 지오코더는 2개 이상의 결과를 반환할 수 있습니다.

google.maps.Geocoder 생성자 객체를 통해 코드 내에서 Google 지도 API 지오코딩 서비스에 액세스합니다. Geocoder.geocode() 메서드는 지오코딩 서비스에 요청을 시작하여 응답 수신 시 실행할 입력 용어와 콜백 메서드가 포함된 GeocoderRequest 객체 리터럴에 이를 전달합니다.

GeocoderRequest 객체 리터럴에는 다음 필드가 포함되어 있습니다.

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

필수 매개변수: 다음 필드 중 하나만 입력해야 합니다.

  • address — 지오코딩하려는 주소입니다.
    또는
    location — 사람이 읽을 수 있는 가장 가까운 주소를 얻고자 하는 LatLng (또는 LatLngLiteral)입니다. 지오코더가 역 지오코딩을 수행합니다. 자세한 내용은 역 지오코딩을 참고하세요.
    또는
    placeId — 사람이 읽을 수 있는 가장 가까운 주소를 얻고자 하는 장소의 ID입니다. 장소 ID별 주소 검색에 관해 자세히 알아보세요.

선택 매개변수:

  • bounds — 지오코딩 결과가 더 눈에 띄게 편향되는 LatLngBounds입니다. bounds 매개변수는 지오코더의 결과에 영향을 줄 뿐이고 완전히 구속하지는 않습니다. 아래에서 표시 영역 편향에 대해 자세히 알아보세요.
  • componentRestrictions — 결과를 특정 영역으로 제한하는 데 사용됩니다. 아래에서 구성요소 필터링에 대한 자세한 내용을 참조하세요.
  • region: 2자리 문자 (숫자가 아님) 유니코드 지역 하위 태그로 지정된 지역 코드입니다. 대부분의 경우 이러한 태그는 익숙한 ccTLD(최상위 도메인) 2문자 값에 직접 매핑됩니다. region 매개변수는 지오코더의 결과에 영향을 줄 뿐이고 완전히 구속하지는 않습니다. 자세한 내용은 아래의 지역 코드 편중을 참조하세요.

지오코딩 응답

지오코딩 서비스에서 지오코더 결과를 검색할 때 실행할 콜백 메서드가 필요합니다. 이 콜백은 매개변수 두 개를 전달하여 resultsstatus 코드를 순서대로 유지해야 합니다.

지오코딩 결과

GeocoderResult 객체는 단일 지오코딩 결과를 나타냅니다. 지오코드 요청은 여러 결과 객체를 반환할 수 있습니다.

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

다음은 필드에 대한 설명입니다.

  • types[]는 반환된 결과의 주소 유형을 나타내는 배열입니다. 이 배열에는 결과에 반환된 특성 유형을 식별하는 0개 이상의 태그 집합이 포함됩니다. 예를 들어 '시카고'의 지오코딩은 '시카고'가 도시임을 나타내며 '시각적'도 정치 항목임을 나타내는 '시정 지역'을 반환합니다. 자세한 내용은 아래의 주소 유형 및 주소 구성요소 유형을 참고하세요.
  • 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 수는 요청된 주소에 따라 다르며, 동일한 주소를 대상으로 시간이 지남에 따라 변경될 수 있습니다. 구성요소는 배열에서 위치를 변경할 수 있습니다. 구성요소의 유형은 변경할 수 있습니다. 특정 구성요소가 이후 응답에서 누락될 수 있습니다.

    자세한 내용은 아래의 주소 유형 및 주소 구성요소 유형을 참고하세요.

  • partial_match는 지오코더가 원래 요청과 정확히 일치하는 결과를 반환하지 않았지만, 요청된 주소의 일부분과 일치할 수 있음을 나타냅니다. 맞춤법 오류 또는 불완전한 주소가 있는지 원래 요청을 확인하는 것이 좋습니다.

    부분 일치는 주로 요청에서 전달한 지역 내에 존재하지 않는 상세 주소가 있는 경우에 발생합니다. 요청이 동일한 지역에 있는 두 개 이상의 위치와 일치하는 경우에도 부분 일치가 반환될 수 있습니다. 예를 들어 "Hillpar St, Bristol, UK'는 Henry Street와 Henrietta Street 모두에 대해 부분 일치를 반환합니다. 요청에 맞춤법이 잘못된 주소 구성요소가 포함된 경우 지오코딩 서비스에서 대체 주소를 제안할 수 있습니다. 이 방법으로 트리거되는 추천도 부분 일치로 표시됩니다.

  • place_id는 다른 Google API와 함께 사용할 수 있는 장소의 고유 식별자입니다. 예를 들어 Google Places API 라이브러리와 함께 place_id을 사용하여 전화번호, 영업시간, 사용자 리뷰 등의 지역 비즈니스 세부정보를 가져올 수 있습니다. 장소 ID 개요를 참고하세요.
  • postcode_localities[]는 우편번호에 포함된 모든 지역을 나타내는 배열이며 결과가 여러 지역을 포함하는 우편번호인 경우에만 존재합니다.
  • geometry에는 다음 정보가 포함됩니다.

    • location에는 지오코딩된 위도,경도 값이 포함되어 있습니다. 이 위치는 형식이 지정된 문자열이 아닌 LatLng 객체로 반환됩니다.
    • location_type는 지정된 위치에 대한 추가 데이터를 저장합니다. 현재 지원되는 값은 다음과 같습니다.
      • ROOFTOP는 반환된 결과가 정확한 지오코드를 반영함을 나타냅니다.
      • RANGE_INTERPOLATED은 반환된 결과가 일반적으로 도로에서 정확한 두 지점(예: 교차로) 간에 보간된 근사값을 반영함을 나타냅니다. 보간된 결과는 일반적으로 상세 주소에 루프톱 지오코딩을 사용할 수 없는 경우 반환됩니다.
      • GEOMETRIC_CENTER은 반환된 결과가 다중선 (예: 거리) 또는 다각형(지역)과 같이 결과의 기하학적 중심임을 나타냅니다.
      • APPROXIMATE는 반환된 결과가 근사치임을 나타냅니다.

    • viewport는 반환된 결과에 권장되는 표시 영역을 저장합니다.
    • 선택적으로 반환되는 bounds는 반환된 결과를 완전히 포함할 수 있는 LatLngBounds를 저장합니다. 참고로, 이러한 경계가 권장 뷰포트와 일치하지 않을 수도 있습니다. 예를 들어 샌프란시스코에는 기술적으로 도시에 속한 패럴론 제도가 포함되어 있지만 표시 영역에 반환되면 안 됩니다.

이 주소는 지오코더가 브라우저의 기본 언어 설정이나 language 매개변수를 사용하여 API 자바스크립트를 로드할 때 지정된 언어를 사용하여 반환됩니다. 자세한 내용은 현지화를 참고하세요.

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

GeocoderResulttypes[] 배열은 주소 유형을 나타냅니다. types[] 배열은 GeocoderAddressComponent 내에서 반환되어 특정 주소 구성요소의 유형을 나타낼 수도 있습니다. 지오코더에서 반환한 주소는 여러 유형을 가질 수 있고 그 유형은 태그로 간주될 수 있습니다. 예를 들어 여러 도시는 politicallocality 유형으로 태그됩니다.

지오코더에서는 주소 유형과 주소 구성요소 유형 모두에서 다음 유형을 지원하고 반환합니다.

  • street_address는 정확한 번지수를 나타냅니다.
  • route는 이름이 지정된 경로 (예: "US 101")를 나타냅니다.
  • intersection는 일반적으로 두 주요 도로의 주요 교차로를 나타냅니다.
  • political는 정치적 항목을 나타냅니다. 일반적으로 이 유형은 일부 민간 행정기관의 다각형을 나타냅니다.
  • country는 국가 정치적 항목을 나타내며 일반적으로 지오코더에서 반환하는 가장 높은 주문 유형입니다.
  • administrative_area_level_1는 국가 수준 아래의 첫 번째 도시 항목을 나타냅니다. 미국 내에서 이러한 행정 수준은 주입니다. 모든 국가에 이러한 행정 수준이 표시되는 것은 아닙니다. 대부분의 경우 admin_area_level_1 짧은 이름은 ISO 3166-2 하위 그룹 및 기타 널리 순환되는 목록과 밀접하게 일치합니다. 하지만 지오코딩 결과는 다양한 신호 및 위치 데이터를 기반으로 하므로 보장되지 않습니다.
  • administrative_area_level_2는 국가 수준 아래 두 번째 도시 항목을 나타냅니다. 미국 내에서 이러한 행정구역은 카운티입니다. 모든 국가에 이러한 행정 수준이 표시되는 것은 아닙니다.
  • administrative_area_level_3는 국가 수준 아래 세 번째 도시 항목을 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
  • administrative_area_level_4는 국가 수준 아래 4순위 정부 기관을 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
  • administrative_area_level_5는 국가 수준 아래 5순위 정부 기관을 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
  • administrative_area_level_6는 국가 수준 아래 6번째 정부 항목을 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
  • administrative_area_level_7는 국가 수준 아래 7순위 정부 기관을 나타냅니다. 이 유형은 하위 정부 구역을 나타냅니다. 모든 국가에 이러한 행정 레벨이 있는 것은 아닙니다.
  • colloquial_area는 항목에 일반적으로 사용되는 대체 이름을 나타냅니다.
  • locality는 도시 또는 마을의 통합 법인을 나타냅니다.
  • sublocality는 지역 아래의 1차 정부 기관을 나타냅니다. 일부 위치의 경우 추가 유형 중 하나(sublocality_level_1~sublocality_level_5)를 받을 수 있습니다. 각 하위 지방 레벨은 하나의 정부 엔터티입니다. 숫자가 클수록 더 작은 지역을 나타냅니다.
  • neighborhood은 이름이 지정된 인근 지역을 나타냅니다.
  • premise은 이름이 지정된 위치, 일반적으로 공통 이름을 가진 건물 또는 여러 건물을 나타냅니다.
  • subpremise은 이름이 지정된 위치 아래의 1순위 항목을 나타내며, 일반적으로 공통 이름을 가진 건물 모음 내의 단일 건물을 나타냅니다.
  • plus_code는 위도와 경도에서 파생된 인코딩된 위치 참조를 나타냅니다. Plus Code는 존재하지 않는 위치 (건물에 번호가 지정되지 않았거나 거리 이름이 없는 경우)를 대체할 수 있습니다. 자세한 내용은 https://plus.codes를 참고하세요.
  • postal_code는 국가 내 우편번호를 처리하는 데 사용되는 우편번호를 나타냅니다.
  • natural_feature은 주요 자연 지형을 나타냅니다.
  • airport는 공항을 나타냅니다.
  • park는 이름이 지정된 공원을 나타냅니다.
  • point_of_interest는 이름이 지정된 관심 장소를 나타냅니다. 일반적으로 이러한 관심 장소는 '엠파이어 스테이트 빌딩'이나 '에펠탑'과 같이 다른 카테고리에 잘 맞지 않는 중요한 지역 항목입니다.

유형 목록이 비어 있으면 특정 주소 구성요소에 대해 알려진 유형이 없음을 나타냅니다(예: 프랑스의 Lieu-dit).

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

참고: 이 목록에는 일부만 나와 있으며 변경될 수 있습니다.

  • floor는 건물 주소의 층을 나타냅니다.
  • establishment는 일반적으로 분류되지 않은 장소를 나타냅니다.
  • landmark는 내비게이션을 돕기 위해 참조로 사용되는 주변 장소를 나타냅니다.
  • point_of_interest는 이름이 지정된 관심 장소를 나타냅니다.
  • parking는 주차장 또는 주차 시설을 나타냅니다.
  • post_box는 특정 우편함을 나타냅니다.
  • postal_town은 일부 국가의 우편 주소에 사용되는 localitysublocality와 같은 지리적 그룹의 그룹을 나타냅니다.
  • room는 건물 주소의 회의실을 나타냅니다.
  • street_number는 정확한 번지수를 나타냅니다.
  • bus_station, train_station, transit_station는 버스, 기차, 대중교통 정류장의 위치를 나타냅니다.

상태 코드

status 코드는 다음 값 중 하나를 반환할 수 있습니다.

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

이 예에서는 주소를 지오코딩하고 반환된 위도와 경도 값에 마커를 배치합니다. 핸들러는 익명 함수 리터럴로 전달됩니다.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

예 보기

뷰포트 편중

지오코딩 서비스가 지정된 표시 영역 내의 결과를 선호하도록 지시할 수 있습니다 (경계 상자로 표현됨). 표시 영역 경계를 정의하기 위해 GeocoderRequest 객체 리터럴 내에 bounds 매개변수를 설정하면 됩니다. 편향은 경계 내의 결과만 선호하며, 이 경계 외부에 관련성이 더 높은 결과가 있으면 포함될 수 있습니다.

예를 들어 '위네트카'의 지오코드는 일반적으로 다음의 시카고 외곽 지역을 반환합니다.

{
  "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":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

하지만 bounds 매개변수를 지정하여 로스앤젤레스의 샌 페르난도 밸리에 대한 경계 상자를 정의하면 이 지오코딩이 그 위치에서 "Winnetka"라는 인근 지역을 반환합니다.

{
  "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": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

지역 코드 편중

region 매개변수를 사용하여 지오코딩 서비스에서 특정 지역에 편향된 결과를 명시적으로 반환하도록 설정할 수 있습니다. 이 매개변수는 영숫자가 아닌 2자리 유니코드 지역 하위 태그로 지정된 지역 코드를 사용합니다. 이러한 태그는 "co.uk"에서와 같이 익숙한 ccTLD(“최상위 도메인”) 두 문자 값에 직접 매핑됩니다. 간혹 region 태그가 ISO-3166-1 코드를 지원하며, 이는 종종 ccTLD 값과 다릅니다(예: 영국의 경우 "GB).

region 매개변수를 사용하는 경우:

  • 하나의 국가 또는 지역만 지정하세요. 여러 개의 값이 무시되므로 요청이 실패할 수 있습니다.
  • 2자리 지역 하위 태그 (유니코드 CLDR 형식)만 사용하세요. 다른 모든 입력은 오류를 생성합니다.
  • Google Maps Platform 서비스 지역 세부정보에 나열된 국가 및 지역만 지원됩니다.

지오코딩 요청은 기본 Google 지도 애플리케이션이 지오코딩을 제공하는 모든 도메인에 전송될 수 있습니다. 편향은 특정 도메인의 결과만 선호하며, 이 도메인 외부에 관련성이 더 높은 결과가 있으면 포함될 수 있습니다.

예를 들어 quot;Toledo"에 대한 지오코딩은 지오코딩 서비스의 기본 도메인이 미국으로 설정되므로 이 결과를 반환합니다.

{
  "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"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

region 필드가 'es' (스페인)로 설정된 "Toledo&quot의 지오코딩은 스페인 도시를 반환합니다.

{
  "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"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

구성 요소 필터링

구성요소 필터를 사용하면 지오코딩 서비스가 특정 영역으로 제한된 주소 결과를 반환하도록 설정할 수 있습니다. componentRestrictions 매개변수에 필터를 지정합니다. 필터 값은 다른 지오코딩 요청과 동일한 맞춤법 수정 및 부분 일치 방법을 지원합니다.

지오코더는 모든 구성요소 필터와 일치하는 결과만 반환합니다. 즉, 필터 사양을 OR이 아닌 AND로 평가합니다.

구성요소 필터는 다음 중 하나 이상의 항목으로 구성됩니다.

  • route는 노선의 긴 이름 또는 짧은 이름과 일치합니다.
  • locality는 지역 및 하위 지역 유형과 일치합니다.
  • administrativeArea은 모든 관리 영역 수준과 일치합니다.
  • postalCode는 우편번호와 일치합니다.
  • country은 국가 이름이나 두 글자의 ISO 3166-1 국가 코드와 일치합니다. 참고: API는 국가를 정의할 때 ISO 표준을 준수하며, 해당하는 국가의 ISO 코드를 사용할 때 필터링이 가장 잘 작동합니다.

다음 예시에서는 componentRestrictions 매개변수를 사용하여 countrypostalCode로 필터링하는 방법을 보여줍니다.

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

역지오코딩(주소 조회)

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

텍스트 address를 제공하는 대신 location 매개변수에 쉼표로 구분된 위도/경도 쌍을 제공합니다.

다음 예에서는 위도/경도 값을 지오코딩하고 지도의 중심을 그 위치에 둔 다음, 형식이 지정된 주소로 정보 창을 표시합니다.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

자바스크립트

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
예 보기

샘플 사용해 보기

이전 예시에서는 results[0]를 선택하여 첫 번째 결과를 표시했습니다. 역 지오코더는 결과를 두 개 이상 반환하는 경우가 많습니다. 지오코딩된 주소는 우편 주소가 아니라 위치를 지리적으로 명명하는 방법입니다. 예를 들어 시카고시의 한 지점을 지오코딩할 때 지오코딩된 지점은 상세 주소, 도시 (시카고), 주 (일리노이) 또는 국가 (미국)로 라벨이 지정될 수 있습니다. 이들은 모두 지오코더에게 주소가 됩니다. 역 지오코더는 이러한 결과를 모두 반환합니다.

역 지오코더는 정치적 항목 (국가, 주, 도시 및 인근 지역), 상세 주소, 우편번호와 일치합니다.

다음은 위 쿼리에서 반환될 수 있는 주소 목록의 예입니다.

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

주소는 일치도가 가장 높은 주소에서 낮은 주소 순으로 반환됩니다. 일반적으로 이 경우처럼 더 정확한 주소가 가장 눈에 띄는 결과입니다. Google에서는 가장 구체적인 상세 주소부터 인근 지역, 도시, 카운티, 주 등 보다 구체적인 정치적 항목에 이르기까지 다양한 유형의 주소를 반환합니다. 보다 일반적인 주소와 일치시키려면 results[].types 필드를 검사하는 것이 좋습니다.

참고: 역 지오코딩은 정확한 과학이 아닙니다. 지오코더는 특정 오차 범위 내에서 가장 가까운 주소 지정 위치를 찾습니다.

장소 ID의 주소 가져오기

특정 장소 ID의 주소를 찾을 수 있도록 placeId를 제공합니다. 장소 ID는 다른 Google API와 함께 사용할 수 있는 고유 식별자입니다. 예를 들어 Roads API에서 반환된 placeId를 제공하여 맞추기 지점의 주소를 가져올 수 있습니다. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참고하세요.

placeId를 제공하면 요청에 다음 필드가 포함될 수 없습니다.

  • address
  • latLng
  • location
  • componentRestrictions

다음 예는 장소 ID를 수락하고 해당 주소를 찾아 그 위치에 지도의 중심을 맞춥니다. 또한 관련 장소의 형식이 지정된 주소를 표시하는 정보 창이 표시됩니다.

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

자바스크립트

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
예 보기

샘플 사용해 보기