주소 지오코딩

유럽 경제 지역 (EEA) 개발자

지오코딩은 주소를 지도상의 위치로 변환합니다. 주소를 지오코딩하면 응답에 다음이 포함됩니다.

  • 위치의 장소 ID
  • 위치의 위도 및 경도 좌표
  • 위치의 Plus Code
  • 확장된 주소 세부정보

지오코드 요청

지오코드 요청은 HTTP GET 요청입니다. 주소를 구조화되지 않은 문자열로 지정할 수 있습니다.

https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING

또는 쿼리 매개변수로 표시되는 구조화된 주소 구성요소 집합으로

https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS

일반적으로 HTML 양식에서 캡처된 주소 구성요소를 처리할 때는 구조화된 형식을 사용합니다.

다른 모든 매개변수는 URL 매개변수로 전달하거나, API 키 및 필드 마스크와 같은 매개변수의 경우 GET 요청의 일부로 헤더에 전달합니다.

구조화되지 않은 주소 문자열 전달

구조화되지 않은 주소는 문자열 또는 Plus Code로 형식이 지정된 주소입니다. 예를 들어 다음 예에서는 URL 인코딩된 주소 문자열 '1600 Amphitheatre Parkway, Mountain View, CA'를 전달합니다.

https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

URL의 '+' 문자가 공백으로 변환됩니다.

curl 명령어를 사용하여 요청할 수도 있습니다.

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

주소에는 다양한 유형의 특수문자가 포함될 수 있습니다. 예를 들어 '7/1 King St, Concord West'와 같이 '/'를 사용합니다. '/'를 %2F로 URL 인코딩합니다.

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

또 다른 일반적인 예는 '9500 W Bryn Mawr Ave #650, Rosemont'와 같이 '#' 문자입니다. '#'을 %2FE로 URL 인코딩합니다.

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

다음 예에서는 구조화되지 않은 주소 문자열을 플러스 코드 849VCWC8+R4로 지정합니다. '+' 문자를 %2B로 URL 인코딩해야 합니다.

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

구조화된 주소 전달

PostalAddress 유형의 address 쿼리 매개변수를 사용하여 구조화된 주소를 지정합니다. PostalAddress 객체를 사용하면 요청에서 주소 구성요소의 일부 또는 전부를 개별 쿼리 매개변수로 지정할 수 있습니다.

예를 들어 주소의 우편번호만 지정하려면 PostalAddress.postalCode를 사용합니다.

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

HTML 양식에서 캡처된 주소 구성요소와 같이 여러 주소 구성요소를 지정하려면 여러 쿼리 매개변수를 사용하세요.

https://geocode.googleapis.com/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

OAuth를 사용하여 요청하기

Geocoding API v4는 인증에 OAuth 2.0을 지원합니다. Geocoding API에서 OAuth를 사용하려면 OAuth 토큰에 올바른 범위가 할당되어야 합니다. Geocoding API는 순방향 지오코딩과 함께 사용할 수 있는 다음 범위를 지원합니다.

  • https://www.googleapis.com/auth/maps-platform.geocode — 모든 Geocoding API 엔드포인트와 함께 사용합니다.
  • https://www.googleapis.com/auth/maps-platform.geocode.address — 순방향 지오코딩에 GeocodeAddress와 함께만 사용합니다.

또한 모든 Geocoding API 엔드포인트에 일반 https://www.googleapis.com/auth/cloud-platform 범위를 사용할 수 있습니다. 이 범위는 모든 엔드포인트에 대한 액세스를 허용하는 일반 범위이므로 개발 중에는 유용하지만 프로덕션에서는 유용하지 않습니다.

자세한 내용과 예는 OAuth 사용을 참고하세요.

지오코드 응답

지오코딩은 GeocodeResult 객체의 results 배열을 포함하는 GeocodeAddressResponse 객체를 반환합니다. 각 GeocodeResult 객체는 단일 장소를 나타냅니다.

전체 JSON 객체는 다음 형식입니다.

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

필수 매개변수

  • address - 지오코딩할 상세 주소 또는 Plus Code입니다. 관련 국가의 우편 서비스에서 사용하는 형식에 따라 주소를 지정합니다. 업체 이름, 호수, 방 번호, 층 번호와 같은 추가 주소 요소는 피해야 합니다. 상세 주소 요소는 공백으로 구분되어야 하며 URL로 인코딩되어 %20가 되어야 합니다. 예를 들어 주소 '24 Sussex Drive Ottawa ON'을 다음과 같이 전달합니다. 
    24%20Sussex%20Drive%20Ottawa%20ON
     아래와 같이 Plus Code의 형식을 지정합니다. 더하기 기호는 %2B로 URL 인코딩되고 공백은 %20로 URL 인코딩됩니다.
    • 글로벌 코드는 4자리 지역 코드와 6자 이상의 로컬 코드입니다. 예를 들어 '849VCWC8+R9'를 849VCWC8%2BR9로 인코딩합니다.
    • 복합 코드는 명시적인 위치가 포함된 6자 이상의 로컬 코드입니다. 예를 들어 'CWC8+R9 Mountain View, CA, USA'를 CWC8%2BR9%20Mountain%20View%20CA%20USA로 인코딩합니다.

선택적 매개변수

  • locationBias

    검색할 영역을 Viewport로 지정합니다. 이 위치는 편향으로 작용하므로 지정된 위치 주변의 결과가 반환될 수 있습니다. 여기에는 지역 근처에 있지만 지역 외부에 있는 결과도 포함됩니다.

    리전을 직사각형 뷰포트로 지정합니다. 직사각형은 대각선으로 반대되는 두 개의 하한 및 상한 지점으로 표현되는 위도-경도 표시 영역입니다. 낮은 점은 직사각형의 남서쪽 모서리를 표시하고 높은 점은 직사각형의 북동쪽 모서리를 나타냅니다.

    표시 영역은 경계를 포함하는 닫힌 영역으로 간주됩니다. 위도 범위는 -90~90도(포함)여야 하고 경도 범위는 -180~180도(포함)여야 합니다.

    • low = high이면 표시 영역은 단일 점으로 구성됩니다.
    • low.longitude > high.longitude인 경우 경도 범위가 반전됩니다 (표시 영역이 180도 경도선을 교차함).
    • low.longitude = -180도이고 high.longitude = 180도인 경우 뷰포트에는 모든 경도가 포함됩니다.
    • low.longitude = 180도이고 high.longitude = -180도이면 경도 범위가 비어 있습니다.
    • low.latitude > high.latitude이면 위도 범위가 비어 있습니다.

    최저 값과 최고 값 모두 채워야 하며 표시된 상자는 비워 둘 수 없습니다. 빈 뷰포트는 오류를 발생시킵니다.

    예를 들어 이 쿼리 문자열은 뉴욕시를 완전히 둘러싸는 뷰포트를 정의합니다.

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • languageCode

    결과를 반환할 언어입니다.

    • 지원되는 언어 목록을 참고하세요. Google에서는 지원되는 언어를 자주 업데이트하므로 이 목록에 모든 언어가 포함되지 않을 수도 있습니다.
    • languageCode가 제공되지 않으면 API는 기본적으로 en을 사용합니다. 잘못된 언어 코드를 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다.
    • API는 사용자와 현지인 모두가 읽을 수 있는 상세 주소를 제공하기 위해 최선을 다합니다. 이 목표를 달성하기 위해 선호하는 언어를 준수하여 필요한 경우 사용자가 읽을 수 있는 스크립트로 음역된 현지 언어의 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
    • 선호하는 언어로 이름을 사용할 수 없는 경우 API는 가장 일치하는 이름을 사용합니다.
    • 기본 언어는 API가 반환하도록 선택한 결과 집합과 반환되는 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 약어를 다르게 해석합니다. 예를 들어 거리 유형의 약어나 한 언어에서는 유효하지만 다른 언어에서는 유효하지 않은 동의어가 있습니다.

  • regionCode

    두 자리 CLDR 코드 값으로 된 지역 코드입니다. 기본값은 없습니다. 대부분의 CLDR 코드는 ISO 3166-1 코드와 동일합니다.

    주소를 지오코딩할 때(정방향 지오코딩) 이 매개변수는 서비스의 결과를 지정된 지역으로 제한하지는 않지만 영향을 줄 수 있습니다. 위치 또는 장소를 지오코딩할 때(역 지오코딩 또는 장소 지오코딩) 이 매개변수를 사용하여 주소 형식을 지정할 수 있습니다. 모든 경우에 이 매개변수는 관련 법규에 따라 결과에 영향을 줄 수 있습니다.

위치 편향

locationBias 매개변수를 사용하여 지오코딩 서비스에 (경계 상자로 표시된) 지정된 표시 영역의 결과를 선택하도록 지시합니다. locationBias 매개변수는 이 경계 상자의 남서쪽 및 북동쪽 모서리의 위도/경도 좌표를 정의합니다.

예를 들어 'Washington' 주소에 대한 지오코드 요청은 워싱턴 D.C.와 미국 워싱턴주의 결과를 반환할 수 있습니다.

https://geocode.googleapis.com/v4beta/geocode/address/Washington?key=API_KEY

응답은 다음 형식입니다.

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

하지만 locationBias 매개변수를 추가하여 미국 북동부 주변의 경계 상자를 정의하면 이 지오코드에서 워싱턴 D.C.만 반환합니다.

https://geocode.googleapis.com/v4beta/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

리전 바이어스

지오코딩 요청에서 regionCode 매개변수를 사용하여 특정 지역에 편중된 결과를 반환하도록 지오코딩 서비스에 지시할 수 있습니다. 이 매개변수는 지역 편향을 지정하는 2자리 CLDR 코드 값을 사용합니다. 대부분의 CLDR 코드는 ISO 3166-1 코드와 동일합니다.

regionCode에는 기본값이 없습니다. 예를 들어 'Toledo'의 지오코드는 미국과 스페인의 결과를 반환합니다.

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?key=API_KEY

응답:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

regionCode=es (스페인)이 포함된 'Toledo'의 지오코딩 요청은 스페인의 결과만 반환합니다.

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY