science 이 제품 또는 기능은 미리보기 버전 (GA 이전)에 있습니다. GA 이전 제품과 기능에 대한 지원이 제한될 수 있으며 GA 이전 제품과 기능의 변경사항이 다른 GA 이전 버전과 호환되지 않을 수 있습니다. GA 이전 버전 제품 및 서비스에는
Google Maps Platform 서비스별 약관이 적용됩니다. 자세한 내용은
출시 단계 설명을 참조하세요.
장소 지오코딩
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
장소 지오코딩을 사용하면 장소 ID에서 주소를 가져올 수 있습니다.
장소 ID는 Google 지역 정보 데이터베이스 및 Google 지도에 있는 장소를 고유하게 나타냅니다. 주소를 지오코딩할 때 장소 ID를 가져옵니다. 장소 세부정보 (신규), 텍스트 검색 (신규), 주변 지역 검색(신규)과 같은 다른 여러 API에서 장소 ID를 가져올 수도 있습니다.
장소 지오코딩 요청
장소 지오코딩 요청은 다음과 같은 형태의 HTTP GET 요청입니다.
https://geocode.googleapis.com/v4beta/geocode/places/PLACE_ID
여기서 PLACE_ID에는 관심 위치의 장소 ID가 포함됩니다.
다른 모든 매개변수는 URL 매개변수로 전달하거나, API 키 또는 필드 마스크와 같은 매개변수의 경우 GET 요청의 일부로 헤더에 전달합니다. 예를 들면 다음과 같습니다.
https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY
또는 curl 명령어에서 다음을 입력합니다.
curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
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.place
— 장소 지오코딩에 GeocodePlace와 함께만 사용합니다.
또한 모든 Geocoding API 엔드포인트에 일반 https://www.googleapis.com/auth/cloud-platform 범위를 사용할 수 있습니다. 이 범위는 모든 엔드포인트에 대한 액세스를 허용하는 일반 범위이므로 개발 중에는 유용하지만 프로덕션에서는 유용하지 않습니다.
자세한 내용과 예는 OAuth 사용을 참고하세요.
장소 지오코딩 응답
장소 지오코딩은 장소 ID에 해당하는 장소를 나타내는 GeocodeResult 객체를 반환합니다.
전체 JSON 객체는 다음 형식입니다.
{
"place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
"placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
"location": {
"latitude": 37.4220541,
"longitude": -122.08532419999999
},
"granularity": "ROOFTOP",
"viewport": {
"low": {
"latitude": 37.4209489697085,
"longitude": -122.08846930000001
},
"high": {
"latitude": 37.4236469302915,
"longitude": -122.0829156
}
},
"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"
},
{
"longText": "Mountain View",
"shortText": "Mountain View",
"types": [
"locality",
"political"
],
"languageCode": "en"
},
{
"longText": "Santa Clara County",
"shortText": "Santa Clara County",
"types": [
"administrative_area_level_2",
"political"
],
"languageCode": "en"
},
{
"longText": "California",
"shortText": "CA",
"types": [
"administrative_area_level_1",
"political"
],
"languageCode": "en"
},
{
"longText": "United States",
"shortText": "US",
"types": [
"country",
"political"
],
"languageCode": "en"
},
{
"longText": "94043",
"shortText": "94043",
"types": [
"postal_code"
]
}
],
"types": [
"establishment",
"point_of_interest"
]
}
필수 매개변수
place: 인간이 읽을 수 있는 주소를 얻으려는 장소의 장소 ID입니다. 장소 ID는 다른 Google API에 사용할 수 있는 고유 식별자입니다. 예를 들어 Roads API에서 반환된 placeID를 사용하여 스냅된 지점의 주소를 가져올 수 있습니다. 장소 ID에 대한 자세한 내용은 장소 ID를 참고하세요.
선택적 매개변수
languageCode
결과를 반환할 언어입니다.
-
지원되는 언어 목록을 참고하세요. Google에서는 지원되는 언어를 자주 업데이트하므로 이 목록에 모든 언어가 포함되지 않을 수도 있습니다.
-
languageCode가 제공되지 않으면 API는 기본적으로 en을 사용합니다. 잘못된 언어 코드를 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다.
-
API는 사용자와 현지인 모두가 읽을 수 있는 상세 주소를 제공하기 위해 최선을 다합니다. 이 목표를 달성하기 위해 선호하는 언어를 준수하여 필요한 경우 사용자가 읽을 수 있는 스크립트로 음역된 현지 언어의 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
-
선호하는 언어로 이름을 사용할 수 없는 경우 API는 가장 일치하는 이름을 사용합니다.
-
기본 언어는 API가 반환하도록 선택한 결과 집합과 반환되는 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 약어를 다르게 해석합니다. 예를 들어 거리 유형의 약어나 한 언어에서는 유효하지만 다른 언어에서는 유효하지 않은 동의어가 있습니다.
regionCode
두 자리 CLDR 코드 값으로 된 지역 코드입니다. 기본값은 없습니다. 대부분의 CLDR 코드는 ISO 3166-1 코드와 동일합니다.
주소를 지오코딩할 때(정방향 지오코딩) 이 매개변수는 서비스의 결과를 지정된 지역으로 제한하지는 않지만 영향을 줄 수 있습니다. 위치 또는 장소를 지오코딩할 때(역 지오코딩 또는 장소 지오코딩) 이 매개변수를 사용하여 주소 형식을 지정할 수 있습니다. 모든 경우에 이 매개변수는 관련 법규에 따라 결과에 영향을 줄 수 있습니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-09-05(UTC)
[null,null,["최종 업데이트: 2025-09-05(UTC)"],[],[],null,["# Place geocoding\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\nPlace geocoding lets you retrieve an address from a [place\nID](/maps/documentation/places/web-service/place-id).\n\nPlace IDs uniquely identify a place in the Google Places database and on Google\nMaps. Retrieve place IDs when you [Geocode an\naddress](/maps/documentation/geocoding). You can also retrieve a place ID from many other APIs, such as\n[Place Details (New)](/maps/documentation/places/web-service/place-details),\n[Text Search (New)](/maps/documentation/places/web-service/text-search),\nand [Nearby Search\n(New)](/maps/documentation/places/web-service/nearby-search).\n\nPlace geocoding requests\n------------------------\n\nA\n[place geocoding](/maps/documentation/geocoding/reference/rest/v4beta/geocode.places)\nrequest is an HTTP GET request in the form: \n\n```scdoc\nhttps://geocode.googleapis.com/v4beta/geocode/places/PLACE_ID\n```\n\nWhere \u003cvar translate=\"no\"\u003ePLACE_ID\u003c/var\u003e contains the place ID of the location of interest.\n\nPass all other parameters as URL parameters or, for parameters such as the API\nkey or field mask, in headers as part of the GET request. For example: \n\n```html\nhttps://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY\n```\n\nOr in a curl command: \n\n```\ncurl -X GET -H 'Content-Type: application/json' \\\n-H \"X-Goog-Api-Key: API_KEY\" \\\n\"https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw\"\n```\n\n### Use OAuth to make a request\n\nGeocoding API v4 supports [OAuth\n2.0](/maps/documentation/geocoding/oauth-token) for authentication. To use OAuth\nwith the Geocoding API, the OAuth token must be assigned the correct scope.\nGeocoding API supports the following scopes for use with place geocoding:\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.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\ndevelopment, but not production, because it is a general scope that allows\naccess to all endpoints.\n\nFor more information and examples, see [Use\nOAuth](/maps/documentation/geocoding/oauth-token).\n\nPlace geocoding responses\n-------------------------\n\nPlace geocoding returns a\n[`GeocodeResult`](/maps/documentation/geocoding/reference/rest/v4beta/GeocodeResult)\nobject that represents the place corresponding to the place ID.\n\nThe complete JSON object is in the form: \n\n```json\n{\n \"place\": \"//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw\",\n \"placeId\": \"ChIJj61dQgK6j4AR4GeTYWZsKWw\",\n \"location\": {\n \"latitude\": 37.4220541,\n \"longitude\": -122.08532419999999\n },\n \"granularity\": \"ROOFTOP\",\n \"viewport\": {\n \"low\": {\n \"latitude\": 37.4209489697085,\n \"longitude\": -122.08846930000001\n },\n \"high\": {\n \"latitude\": 37.4236469302915,\n \"longitude\": -122.0829156\n }\n },\n \"formattedAddress\": \"1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA\",\n \"postalAddress\": {\n \"regionCode\": \"US\",\n \"languageCode\": \"en\",\n \"postalCode\": \"94043\",\n \"administrativeArea\": \"CA\",\n \"locality\": \"Mountain View\",\n \"addressLines\": [\n \"1600 Amphitheatre Pkwy\"\n ]\n },\n \"addressComponents\": [\n {\n \"longText\": \"1600\",\n \"shortText\": \"1600\",\n \"types\": [\n \"street_number\"\n ]\n },\n {\n \"longText\": \"Amphitheatre Parkway\",\n \"shortText\": \"Amphitheatre Pkwy\",\n \"types\": [\n \"route\"\n ],\n \"languageCode\": \"en\"\n },\n {\n \"longText\": \"Mountain View\",\n \"shortText\": \"Mountain View\",\n \"types\": [\n \"locality\",\n \"political\"\n ],\n \"languageCode\": \"en\"\n },\n {\n \"longText\": \"Santa Clara County\",\n \"shortText\": \"Santa Clara County\",\n \"types\": [\n \"administrative_area_level_2\",\n \"political\"\n ],\n \"languageCode\": \"en\"\n },\n {\n \"longText\": \"California\",\n \"shortText\": \"CA\",\n \"types\": [\n \"administrative_area_level_1\",\n \"political\"\n ],\n \"languageCode\": \"en\"\n },\n {\n \"longText\": \"United States\",\n \"shortText\": \"US\",\n \"types\": [\n \"country\",\n \"political\"\n ],\n \"languageCode\": \"en\"\n },\n {\n \"longText\": \"94043\",\n \"shortText\": \"94043\",\n \"types\": [\n \"postal_code\"\n ]\n }\n ],\n \"types\": [\n \"establishment\",\n \"point_of_interest\"\n ]\n}\n```\n\nRequired parameters\n-------------------\n\n- `place` --- The place ID of the place for which you want to obtain the human-readable address. The place ID is a unique identifier that can be used with other Google APIs. For example, you can use the `placeID` returned by the [Roads API](/maps/documentation/roads/snap) to get the address for a snapped point. For more information about place IDs, see the [Place IDs](/maps/documentation/places/web-service/place-id).\n\nOptional parameters\n-------------------\n\n-\n\n ### languageCode\n\n The language in which to return results.\n - See the [list of supported languages](/maps/faq#languagesupport). Google often updates the supported languages, so this list may not be exhaustive.\n - If `languageCode` is not supplied, the API defaults to `en`. If you specify an invalid language code, the API returns an `INVALID_ARGUMENT` error.\n - The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.\n - If a name is not available in the preferred language, the API uses the closest match.\n - The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another.\n-\n\n ### regionCode\n\n The region code as a\n [two-character CLDR code](https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html) value. There is no default value. Most CLDR codes are identical to ISO 3166-1 codes.\n\n When geocoding an address, *forward geodcoding* , this parameter can influence, but not\n fully restrict, results from the service to the specified region. When geocoding a location or a\n place, *reverse geocoding* or *place geocoding*, this parameter can be used to\n format the address. In all cases, this parameter can affect results based on applicable law."]]
