모든 준비를 마쳤습니다!

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

Google Maps Geocoding API 활성화

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

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

새 정방향 지오코더 FAQ

이 FAQ에서는 Google Maps APIs의 주소 지오코딩 블로그 게시물에서 발표한 새 정방향 지오코더에 대해 답변합니다. 또한 주소 지오코딩 시의 모범 사례를 참조하세요.

모든 Google Maps APIs에 공통된 질문에 대해서는 Google Maps APIs FAQ를 참조하세요.

시작하기

문제 해결

시작하기

새 정방향 지오코더는 언제 기본 기능이 되나요?
  • 지오코딩 서비스에 대한 Google Maps Geocoding API 및 Google Maps JavaScript API 요청의 경우, 새 정방향 지오코더는 확인되지 않은 요청과 기본 플랜 고객에 대해 이제 기본 기능이 됩니다. 이 API를 사용하는 프리미엄 플랜 고객의 경우 , 이 변경은 2017년 1월 17일에 수행될 예정입니다.
  • Google Maps Directions API, Google Maps Distance Matrix API, Google Static Maps API 및 Google Street View Image API를 사용하는 모든 고객의 경우(기본 플랜 및 프리미엄 플랜) 그리고 길찾기 및 거리 행렬 서비스에 대한 Google Maps JavaScript API 요청의 경우, 새 정방향 지오코더는 2017년 1월 24일에 기본 기능이 될 예정입니다.
  • 구형 지오코더는 2017년 3월말에 영구 중단될 것입니다.

동일 시기에 출시되는 다른 기능들이나 예측하지 못한 문제들에 대해 이들 날짜가 지연될 가능성이 있습니다. 새 지오코더가 배포되기 전에 시스템을 조금이라도 변경하려는 경우, 이들 날짜 전에 이 변경사항을 프로덕션에 적용해야 합니다.

어떤 API가 새로운 정방향 지오코더를 사용하나요?

다음 Google Maps APIs가 다음 요청에 대해 동일한 지오코더를 사용합니다.

참고: 장소 ID의 세부정보를 검색할 때는 새 정방향 지오코더가 절대 사용되지 않습니다.

새 정방향 지오코더가 기본 기능이 되기 전에 이 지오코더를 사용하려면 어떻게 하나요?

이제 Geocoding API, Directions API, Distance Matrix API 그리고 Maps JavaScript API에서 사용 가능한 지오코딩, 길찾기거리 행렬 서비스에서 새 정방향 지오코더를 사용할 수 있습니다.

Geocoding API, Directions API 및 Distance Matrix API의 경우, 선택 항목인 new_forward_geocoder=true 매개변수를 요청에 추가하세요.

Google Maps APIs 웹 서비스 클라이언트 라이브러리의 경우, 새 정방향 지오코더를 사용하려면 new_forward_geocoder=true를 요청에 추가하세요. 이것은 최근에 클라이언트 라이브러리에 추가된 사용자 지정 URL 매개변수입니다.

Maps JavaScript API에서 사용 가능한 지오코딩, 길찾기거리 행렬 서비스의 경우, 적절한 요청 객체에서 새 선택 항목 매개변수인 newForwardGeocoder: true를 설정하세요. 이 매개변수는 시험용 버전과 릴리스 버전에서 사용이 가능합니다.

한 가지 선택 항목 설정으로 Google Maps API 지오코더 도구가 업데이트되었습니다. 도구 사용 시, 새 정방향 지오코더 기능에 따라 결과를 생성하려면 "새 정방향 지오코더 사용"을 선택하세요.

참고: 새 정방향 지오코더는 아직 Static Maps API 및 Street View Image API에서 사용할 수 없습니다.

구형 정방향 지오코더가 기본 기능이 아닌 경우 이 지오코더를 사용하려면 어떻게 하나요?

2017년 3월 29일의 영구 중단까지는 구형 정방향 지오코더를 계속 사용할 수 있습니다.

Geocoding API, Directions API 및 Distance Matrix API의 경우, 선택 항목인 new_forward_geocoder=false 매개변수를 요청에 추가하세요.

Google Maps APIs 웹 서비스 클라이언트 라이브러리의 경우, 구형 정방향 지오코더를 사용하려면 new_forward_geocoder=false를 요청에 추가하세요. 이것은 최근에 클라이언트 라이브러리에 추가된 사용자 지정 URL 매개변수입니다.

Maps JavaScript API에서 사용 가능한 지오코딩, 길찾기거리 행렬 서비스의 경우, 적절한 요청 객체에서 새 선택 항목 매개변수인 newForwardGeocoder: false를 설정하세요. 이 매개변수는 시험용 버전과 릴리스 버전에서 사용이 가능합니다.

참고: Static Maps API 및 Street View Image API의 경우 새 정방향 지오코더를 아직 사용할 수 없으므로, 이 옵션을 false로 설정할 필요가 없습니다. 이제 Static Maps API 및 Street View Image API는 구형 정방향 지오코더를 계속 사용할 수 있습니다.

이 변경이 생긴 이유는 무엇인가요?

새 정방향 지오코더는 소비자 Google 지도 애플리케이션에 사용되는 것과 동일한 것입니다. 구형 지오코더는 지원이 중단될 것입니다.

이 변경은 이전 버전과 호환되나요?

네, Geocoding API는 동일한 요청 및 응답 형식을 유지합니다. 새 지오코더는 상당수 쿼리에 대해 다른 결과 세트를 생성할 수 있지만, 요청은 현재 형식을 그대로 계속 유지하며 새로운 결과는 동일 필드를 반환합니다.

문제 해결

새 지오코더에서 더 많은 쿼리들이 ZERO_RESULTS를 반환합니다. 그 이유가 무엇인가요?

새 지오코더에서는 모호하고 불완전하고 형식이 잘못된 쿼리가 ZERO_RESULTS를 생성할 수도 있습니다. 일반적으로 이러한 쿼리는 구형 지오코더에서 잘못된 결과를 생성할 수 있습니다(예: 주소를 찾을 수 없을 때 교외를 반환). 이러한 상황에서는 ZERO_RESULTS를 반환하는 것이 실제로 더 올바른 응답이라고 저희는 생각합니다.

애플리케이션이 사용자 입력 주소를 처리하는 경우, Places API의 장소 자동완성 기능이 더 나은 결과를 생성할 수도 있습니다. 장소 자동완성에서 사용자는 자신이 입력한 내용에 따라 결과 세트를 선택할 수 있습니다. 이 경우 사용자는 비슷한 이름의 여러 결과 중에서 하나를 선택할 수 있고 자신이 주소를 잘못 입력한 경우 쿼리를 조정할 수 있습니다.

자동 시스템(자동완성 제안으로부터 항목을 선택할 사용자가 없는 시스템)으로부터 애플리케이션에 입력이 제공될 때 이 애플리케이션이 모호하거나 불완전한 쿼리를 처리하거나 비주소 형식 요소(예: 사업체 이름)가 포함된 쿼리를 처리하는 경우에는, Places API 텍스트 검색이 더 나은 선택일 수 있습니다. 텍스트 검색은 모호한 쿼리에 대해 하나의 결과를 반환할 가능성이 더 높습니다. 왜냐하면 이러한 쿼리에는 Geocoding API가 고려하지 않는 사업체 이름이 포함될 수도 있기 때문입니다.

애플리케이션이 모호하거나 불완전한 쿼리를 처리하거나 비주소 형식 요소가 포함된 쿼리를 처리하는 경우에는, Geocoding API에 제공되는 정방향 지오코더 대신 Places API를 사용하는 것이 좋습니다. 더 자세한 내용은 주소 지오코딩 시의 모범 사례Google Maps API에서 주소 지오코딩 블로그 게시물을 참조하세요.

저는 고속 응답이 필요한데, 새 지오코더는 제 애플리케이션에서 너무 느립니다. 더 빠른 응답을 위해 무엇을 사용해야 하나요?

사용자 입력에 응답하는 애플리케이션 중에서 지연 시간에 매우 민감한 애플리케이션을 사용하는 것이 좋습니다. 주소 지오코딩을 사용하는 대신 Places API의 장소 자동완성 기능을 사용하세요(JavaScript, Android 또는 iOS에서도 사용 가능). 장소 자동완성은 대화형 방식으로 사용이 최적화되기 때문에, 지연 시간이 매우 짧습니다.

Geocoding API의 주소 지오코딩은 명확하고 완전하고 형식이 올바른 주소(예: 온라인 양식에 입력된 배송 주소)에 사용하도록 최적화되기 때문에, 장소 자동완성보다 지연 시간이 더 깁니다. 이것은 구형 정방향 지오코더와 마찬가지입니다. 장소 자동완성과 새 정방향 지오코더 사이의 지연 시간 차는 더 커집니다. 왜냐하면 새 지오코더는 지연 시간은 약간 더 길지만 커버리지와 검색 결과는 더 낫기 때문입니다.

Directions API 및 Distance Matrix API에서 지연 시간을 줄이려면 어떻게 하나요?

주소 대신에 장소 ID를 사용하여 경유지, 출발지 및 목적지를 지정합니다. 장소 ID는 Places API의 장소 자동완성 기능이나 Maps JavaScript API의 장소 라이브러리에서 정확하게 구할 수 있습니다. placeIdOnly 옵션에 대한 자세한 내용을 참조하세요. 이 옵션은 장소 자동완성 비용을 줄이는 데 사용됩니다.

장소 ID 또는 latlng 대신 주소 문자열을 가지고 Directions API 또는 Distance Matrix API에 쿼리를 수행하는 경우, Geocoding API와 동일한 백엔드를 사용하여 해당 주소를 장소 ID로 변환하고 그 후에 길찾기를 계산합니다. 장소 자동완성은 주소 지오코딩보다 더 빠릅니다. 지연 시간이 매우 민감한 상황에서 Directions API 또는 Distance Matrix API를 사용하는 애플리케이션의 경우(예: 사용자 입력에 응답), 장소 자동완성을 사용하여 해당 주소의 장소 ID를 구한 다음, 이 장소 ID를 Directions API 또는 Distance Matrix API에 전달하는 것이 좋습니다. 이 접근방식은 구형 주소 지오코더에 비해서도 지연 시간을 상당히 줄여줍니다. 길찾기에서 장소 자동완성을 사용하는 방법에 대한 예시 문서를 참조하세요.

저는 고객인데 Places API가 너무 비쌉니다. 비용을 줄이려면 어떻게 하나요?

Maps JavaScript API 장소 autocomplete 위젯을 사용하는 것이 좋습니다. autocomplete 위젯의 사용 비용을 줄이려면, 새로운 placeIdOnly 옵션을 사용하여 장소 자동완성 서비스에서 장소 ID에 대한 직접 액세스를 활성화하세요. placeIdOnly 옵션은 전체 사업체 세부정보 대신 주소만 요구하는 애플리케이션에 대해 장소 세부정보 요청을 건너뜁니다. 해당 주소를 가져오려면 장소 ID를 지오코딩 서비스나 Geocoding API로 전달하세요. 또한 주소 문자열이나 위도/경도 쌍 대신 장소 ID를 길찾기 또는 거리 행렬 서비스나 Directions API 또는 Distance Matrix API에 전달할 수도 있습니다.

새로운 placeIdOnly 옵션의 사용 방법을 보여주기 위해 Google Maps API 지오코더 도구장소 자동완성 및 길찾기 예시가 업데이트되었습니다.

새 지오코더에서 버그를 보고하려면 어떻게 하나요?

새 정방향 지오코더 서비스에 대해 버그 보고 또는 기능 요청이 있는 경우, 공개 Issue Tracker를 사용하여 저희에게 알려주세요.

새 지오코더가 생성하는 결과가 제 사용 사례에 적합치 않습니다. 어떤 도움을 받을 수 있나요?

공개 Issue Tracker를 사용하여 저희에게 알려주시면 새 지오코더에서 더 나쁜 검색 결과를 유발하는 특정 쿼리를 공유할 수 있고, 이를 통해 문제의 원인이 되는 버그나 시스템 문제를 파악할 수 있으며 또한 모범 사례 가이드의 내용을 수정하여 개발자에게 더 나은 검색 결과를 제공할 수 있습니다.

새 지오코더에서의 구성 요소 필터링 작동이 구형 지오코더에서의 작동과 다릅니다. 새 지오코더에서 구성 요소 필터링을 사용하여 최적의 결과를 얻으려면 어떻게 하나요?

새 지오코더에서는 주소 수준별 결과에 대해서만 구성 요소 필터링을 완벽하게 지원합니다. 더 나은 검색 결과를 위해, 국가 코드(예: components=country:GB)와 지역 우편 번호를 부분적으로 제한하기도 합니다. 다음 예시에서는 자신에게 필요한 결과에 따라 구성 요소 필터링을 사용하는 방법을 보여줍니다. 샘플 요청 URL에서 ‘YOUR_API_KEY’를 자신의 실제 API 키로 대체해야 합니다.

  • 건물, 거리, 도로 등의 주소를 정치적 지역(국가, 지방 등)으로 제한하려면, 구형 지오코더와 동일한 방식으로 구성 요소 필터링을 사용하세요. 이러한 사용은 새 지오코더에서 지원됩니다. 예: address=gordon&components=locality:dublin은 "Gordon Way, Dublin, OH 43017, USA"를 반환합니다.
    https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&address=gordon&components=locality:dublin&key=YOUR_API_KEY
    
  • 우편 번호를 특정 국가로 제한하려면, 구형 지오코더와 동일한 방식으로 구성 요소 필터링을 사용하되 ISO 3166-2 국가 코드를 사용하여 국가 제한을 지정해야 합니다. 이러한 사용은 새 지오코더에서 지원됩니다. 예: components=country:CH|postal_code:2000은 "2000 Neuchâtel, Switzerland"를 반환합니다.
    https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=country:CH%7Cpostal_code:2000&key=YOUR_API_KEY
    
  • 다른 비주소 형식 쿼리(도시 또는 근방)를 특정 국가로 제한하려면, 구형 지오코더와 동일한 방식으로 구성 요소 필터링을 사용하되 ISO 3166-2 국가 코드를 사용하여 국가 제한을 지정해야 합니다. 새 지오코더에서는 구형 지오코더와 검색 결과가 동일하리라는 보장이 없습니다. 원하는 국가로 제한된 더 나은 검색 결과를 얻으려면 장소 자동완성을 사용하세요.

    예:

    • 구형 지오코더 사용 시 components=country:US%7Clocality:paris를 지오코딩하면 미국 내 "Paris"라는 이름의 여러 도시들이 반환됩니다.
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=false&components=country:US%7Clocality:paris&key=YOUR_API_KEY
      
    • 새 지오코더 사용 시 components=country:US%7Clocality:paris를 지오코딩하면 "Paris, TX, USA"가 반환되며, 미국 내 "Paris"라는 이름의 다른 도시들은 반환되지 않습니다.
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=country:US%7Clocality:paris&key=YOUR_API_KEY
      
    • input=paris&components=country:us&types=(regions)에 장소 자동완성을 사용하고 또한 locationradius를 사용하는 뷰포트를 지정하여 위치 결과를 편중하면, 미국 내 "Paris"라는 이름의 여러 도시들로 응답이 생성됩니다.
      https://maps.googleapis.com/maps/api/place/autocomplete/json?location=37.386052,-122.083851&radius=10000&input=paris&components=country:us&types=(regions)&key=YOUR_API_KEY
      
  • 다른 비주소 형식 쿼리(예: 도시 또는 근방)를 특정 국가가 아닌 지역으로 제한하는 경우, 새 지오코더에서 구성 요소 필터링을 사용할 때 구형 지오코더와 검색 결과가 동일하리라는 보장이 없습니다. 특정 지역(locationradius)으로 편중된 더 나은 결과를 얻으려면 장소 자동완성을 사용하세요. 또한 새로운 strictbounds 매개변수를 사용하여 특정 지역으로 결과를 제한할 수도 있습니다.

    예:

    • 구형 지오코더 사용 시 administrative_area:Anaga|locality:Santa+Cruz를 지오코딩하면 아낭가 행정 구역뿐만 아니라 '산타크루스 데 테네리페' 지방이 반환됩니다.
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=false&components=administrative_area:Anaga%7Clocality:Santa%20Cruz&key=YOUR_API_KEY
      
    • 새 지오코더 사용 시 administrative_area:Anaga|locality:Santa+Cruz를 지오코딩하면 아낭가 행정 구역만 반환되고 '산타크루스 데 테네리페' 지방은 반환되지 않습니다.
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=administrative_area:Anaga%7Clocality:Santa%20Cruz&key=YOUR_API_KEY
      
    • input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode에 장소 자동완성을 사용하면 먼저 "Santa Cruz de Tenerife, Spain"이 반환될 뿐만 아니라 "Santa Cruz de La Palma", "Santa Cruz, CA, United States"와 같은 다른 도시들도 반환됩니다.
      https://maps.googleapis.com/maps/api/place/autocomplete/json?input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode&key=YOUR_API_KEY
      
    • 특정 지역("Anaga")으로 제한된 결과를 반환하려면 위의 장소 자동완성 요청에 strictbounds를 추가하세요.
      https://maps.googleapis.com/maps/api/place/autocomplete/json?input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode&strictbounds&key=YOUR_API_KEY
      

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

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