Geocoding API는 인증에 OAuth 2.0을 사용하는 것을 지원합니다.
Google은 웹 서버와 같은 일반적인 OAuth 2.0 시나리오를 지원합니다.
이 문서에서는 개발 환경에서 Geocoding API 호출에 OAuth 토큰을 전달하는 방법을 설명합니다. 프로덕션 환경에서 OAuth를 사용하는 방법에 관한 안내는 Google에서 인증을 참고하세요.
시작하기 전에
Geocoding API를 사용하려면 결제 계정이 있고 Geocoding API가 사용 설정된 프로젝트가 필요합니다. 프로젝트 소유자 및 결제 관리자를 여러 명 만들어 이러한 역할을 맡은 담당자가 팀에 상주하도록 하는 것이 좋습니다. 자세한 내용은 Cloud Console에서 설정하기를 참고하세요.
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를 사용해 보려 하지만 토큰을 생성할 환경이 없는 경우 이 섹션의 절차에 따라 호출할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["# Use OAuth\n\n**European Economic Area (EEA) developers** If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](/maps/comms/eea/faq).\n\nGeocoding API supports the use of OAuth 2.0 for authentication.\nGoogle supports common OAuth 2.0 scenarios such as those for a web server.\n\nThis document describes how to pass an OAuth token to the Geocoding API call in your\n**development** environment. For instructions on using OAuth in a\n**production** environment, see\n[Authentication at Google](https://cloud.google.com/docs/authentication).\n| **Note:** While you can use Google Maps APIs directly by making API requests to the server, [client libraries](https://cloud.google.com/apis/docs/client-libraries-explained) provide simplifications that significantly reduce the amount of code you need to write. Google Maps provides client libraries for many programming languages, including Go, Java, Node.js, and Python.\n|\n| \u003cbr /\u003e\n|\n| See [Geocoding API Client Libraries](/maps/documentation/geocoding/client_libraries) for\n| documentation and examples.\n\nBefore you begin\n----------------\n\nBefore you start using the Geocoding API, you need a\nproject with a billing account and the Geocoding API enabled. We recommend creating multiple\nProject Owners and Billing Administrators, so that you'll always have someone with these roles\navailable to your team. To learn more, see [Set up in Cloud Console](/maps/documentation/geocoding/cloud-setup).\n\nAbout OAuth\n-----------\n\nThere are many ways to create and manage access tokens with OAuth based on your deployment\nenvironment.\n\nFor example, the Google OAuth 2.0 system supports server-to-server interactions, such as those\nbetween your application and a Google service. For this scenario you need a service account, which\nis an account that belongs to your application instead of to an individual end user. Your\napplication calls Google APIs on behalf of the service account, so users aren't directly involved.\nFor more information on authentication methods, see\n[Authentication at Google](https://cloud.google.com/docs/authentication).\n\nAlternatively, you might use the Geocoding API as part of an Android or iOS mobile app.\nFor general information on using OAuth with the Geocoding API, including information on managing\naccess tokens for different deployment environments, see\n[Using OAuth 2.0 to Access Google APIs](/identity/protocols/oauth2).\n\nAbout OAuth scopes\n------------------\n\nTo use OAuth with the Geocoding API, the OAuth token must be assigned the correct scope. Geocoding API supports the following scopes:\n\n- `https://www.googleapis.com/auth/maps-platform.geocode` --- Use with all Geocoding API endpoints.\n- `https://www.googleapis.com/auth/maps-platform.geocode.address` --- Use only with `GeocodeAddress` for forward geocoding.\n- `https://www.googleapis.com/auth/maps-platform.geocode.location` --- Use only with `GeocodeLocation` for reverse geocoding.\n- `https://www.googleapis.com/auth/maps-platform.geocode.place` --- Use only with `GeocodePlace` for place geocoding.\n\nAlso, you can use the general `https://www.googleapis.com/auth/cloud-platform`\nscope for all Geocoding API endpoints. That scope is useful during development\nbecause it is the default scope used when creating tokens using\n`gcloud`.\n\n\nExample: Try REST API calls in your local development environment\n-----------------------------------------------------------------\n\nIf you want to try the Geocoding API using an OAuth token, but do not have an environment\nsetup to generate tokens, you can use the procedure in this section to make the call.\n\nThis example describes how to use the OAuth token provided by\n[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials)\nto make the call. For information about using ADC to call Google APIs using client libraries, see\n[Authenticate using client libraries](https://cloud.google.com/docs/authentication/client-libraries).\n| **Note**: The procedure below to make a REST call is not intended for use in a production environment. Use this procedure for a development or testing environment only.\n\n### Prerequisites\n\nBefore you can make a REST request using ADC, use the Google Cloud CLI\nto provide credentials to ADC:\n\n1. If you haven't already, create a project and enable billing by following the steps in the [Set Up in the Google Cloud Console](/maps/documentation/geocoding/cloud-setup).\n2. [Install and initialize the gcloud CLI](https://cloud.google.com/sdk/docs/install?utm_source=Docs_InstallGcloud&utm_content=Docs_geocoding-backend).\n3. Run the following `gcloud` command on your local machine to create your\n credential file:\n\n ```\n gcloud auth application-default login\n ```\n4. A login screen is displayed. After you log in, your credentials are stored in the [local credential file used by ADC](https://cloud.google.com/docs/authentication/application-default-credentials#personal).\n\nFor more information, see\n[Local development environment](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev)\nsection of the\n[Provide credentials for Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc)\ndocumentation.\n\n### Make a REST request\n\nIn this example, you pass two request headers:\n\n- Pass the OAuth token in the `Authorization` header by using the following\n command to generate the token:\n\n [gcloud auth application-default print-access-token](https://cloud.google.com/sdk/gcloud/reference/auth/application-default/print-access-token)\n\n The returned token has a scope of\n `https://www.googleapis.com/auth/cloud-platform.`\n- Pass the ID or name of your Google Cloud project that has billing enabled in the `X-Goog-User-Project` header. To learn more, see [Set up in Cloud Console](/maps/documentation/geocoding/cloud-setup).\n\nThe following example makes a call to the Geocoding API using an OAuth token: \n\n```json\ncurl -X GET -H 'Content-Type: application/json' \\\n-H \"Authorization: Bearer $(gcloud auth application-default print-access-token)\" \\\n-H \"X-Goog-User-Project: PROJECT_ID\" \\\n\"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA\"\n```\n\n\n### Troubleshooting\n\nIf your request returns an error message about end-user credentials not being supported by this API,\nsee [User credentials not working](https://cloud.google.com/docs/authentication/provide-credentials-adc#user-creds-client-based)."]]
