Geocoding API 설정

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

청구서 수신 주소가 유럽 경제 지역에 있는 경우 2025년 7월 8일부터 Google Maps Platform EEA 서비스 약관이 서비스 이용에 적용됩니다. 기능은 리전에 따라 다릅니다. 자세히 알아보기

이 문서에서는 Geocoding API 사용을 시작하는 데 필요한 단계를 설명합니다.

1. 계정 및 결제 기본 요건을 충족하는지 확인합니다.

2. API 사용 설정 Google Cloud 프로젝트에서 API를 사용 설정합니다.

3. 첫 번째 요청하기 인증된 API 요청을 수행하도록 API 키 또는 OAuth를 구성합니다.

핵심사항: 이 설정 가이드에는 API 키 구성과 OAuth 토큰 생성 절차가 모두 포함되어 있습니다. 배포 환경에 적용되는 절차를 선택합니다.

Google Maps Platform 제품은 API 호출에 API 키 또는 OAuth 토큰을 포함하도록 요구하여 무단 사용으로부터 보호합니다.

API 키 OAuth 토큰

OAuth 토큰 만들기

Geocoding API는 인증을 위해 OAuth 2.0 사용을 지원합니다. Google은 웹 서버와 같은 일반적인 OAuth 2.0 시나리오를 지원합니다.

이 문서에서는 개발 환경에서 OAuth 토큰을 Geocoding API 호출에 전달하는 방법을 설명합니다. 프로덕션 환경에서 OAuth를 사용하는 방법은 Google 인증 방법을 참고하세요.

참고:

서버에 API 요청을 수행하여 Google Maps API를 직접 사용할 수 있지만 클라이언트 라이브러리는 작성해야 하는 코드 양을 크게 줄여 주는 간소화 기능을 제공합니다. Google 지도에서는 Go, Java, Node.js, Python을 비롯한 다양한 프로그래밍 언어용 클라이언트 라이브러리를 제공합니다.

문서와 예시는 Geocoding API 클라이언트 라이브러리를 참고하세요.

OAuth 정보

배포 환경에 따라 OAuth를 사용하여 액세스 토큰을 만들고 관리하는 방법은 다양합니다.

예를 들어 Google OAuth 2.0 시스템은 애플리케이션과 Google 서비스 간 상호작용과 같은 서버 간 상호작용을 지원합니다. 이 시나리오에서는 서비스 계정이 필요합니다. 서비스 계정은 개별 최종 사용자가 아닌 애플리케이션에 속한 계정입니다. 애플리케이션이 서비스 계정을 대신하여 Google API를 호출하므로 사용자가 직접 관여하지 않습니다. 인증 방법에 대한 자세한 내용은 Google 인증 방법을 참고하세요.

또는 Android나 iOS 모바일 앱의 일부로 Geocoding API를 사용할 수도 있습니다. 다양한 배포 환경의 액세스 토큰 관리에 관한 정보를 비롯하여 Geocoding API와 함께 OAuth를 사용하는 방법에 관한 일반적인 내용은 OAuth 2.0을 사용하여 Google API에 액세스하기를 참고하세요.

OAuth 범위 정보

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와 함께만 사용
• https://www.googleapis.com/auth/maps-platform.geocode.location — 역 지오코딩을 위해 GeocodeLocation와 함께만 사용합니다.
• https://www.googleapis.com/auth/maps-platform.geocode.place — 장소 지오코딩에 GeocodePlace와 함께만 사용합니다.

또한 모든 Geocoding API 엔드포인트에 일반 https://www.googleapis.com/auth/cloud-platform 범위를 사용할 수 있습니다. 이 범위는 gcloud를 사용하여 토큰을 만들 때 사용되는 기본 범위이므로 개발 중에 유용합니다.

예: 로컬 개발 환경에서 REST API 호출 시도

OAuth 토큰을 사용하여 Geocoding API를 사용해 보고 싶지만 토큰을 생성할 환경이 설정되어 있지 않은 경우 이 섹션의 절차를 사용하여 호출할 수 있습니다.

이 예에서는 애플리케이션 기본 사용자 인증 정보 (ADC)에서 제공하는 OAuth 토큰을 사용하여 호출하는 방법을 설명합니다. ADC를 사용하고 클라이언트 라이브러리를 사용하여 Google API를 호출하는 방법은 클라이언트를 사용하여 인증을 참고하세요.

참고: 아래의 REST 호출 절차는 프로덕션 환경에서 사용할 수 없습니다. 이 절차는 개발 또는 테스트 환경에서만 사용하세요.

기본 요건

ADC를 사용하여 REST 요청을 수행하려면 먼저 Google Cloud CLI를 사용하여 ADC에 사용자 인증 정보를 제공해야 합니다.

1. gcloud CLI를 설치하고 초기화합니다.

2. 로컬 머신에서 다음 gcloud 명령어를 실행하여 사용자 인증 정보 파일을 만듭니다.

   gcloud auth application-default login

3. 로그인 화면이 표시됩니다. 로그인하면 사용자 인증 정보는 ADC에서 사용하는 로컬 사용자 인증 정보 파일에 저장됩니다.

자세한 내용은 로컬 개발 환경의 ADC 설정을 참조하세요.

REST 요청하기

이 예시에서는 두 개의 요청 헤더를 전달합니다.

• 다음 명령어를 사용하여 토큰을 생성하여 Authorization 헤더에서 OAuth 토큰을 전달합니다.

  gcloud auth application-default print-access-token

  반환된 토큰의 범위는 https://www.googleapis.com/auth/cloud-platform.입니다.

• 결제가 사용 설정된 Google Cloud 프로젝트의 ID 또는 이름을 X-Goog-User-Project 헤더에 전달합니다.

다음 예에서는 OAuth 토큰을 사용하여 Geocoding API를 호출합니다.

1. PROJECT_ID 필드를 수정하여 Google Cloud 프로젝트의 ID를 전달합니다.

   curl -X GET -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
   

2. 코드 샘플()에서 복사 아이콘을 클릭하여 curl 명령어를 복사합니다.
3. 터미널 창에 명령어를 붙여넣고 명령어를 실행합니다.

응답은 JSON 객체입니다.

문제 해결

요청이 API에서 지원되지 않는 최종 사용자 인증 정보에 대해 오류 메시지를 반환하는 경우 ADC 설정 문제 해결을 참고하세요.