Geocoding API v4는 풍부한 세부 지역 속성을 위한 목적지 검색과 기본 지오코딩 (좌표-주소 변환)이라는 두 가지 핵심 기능을 제공합니다. 어떤 방법을 사용해야 할지 잘 모르시겠나요? 지오코딩 방법 선택을 참고하세요.
- 목적지 검색 (
SearchDestinations): 건물 입구, 경로 지정이 가능한 탐색 지점, 건물/부지 윤곽선, 하위 목적지, 주변 명소 등 목적지에 대한 풍부한 도착 세부정보를 가져옵니다. - Geocoding (
GeocodeAddress): 상세 주소를 위도 및 경도 좌표로 변환하여 기본 마커를 배치하거나 지도의 중심을 설정합니다. - 역 지오코딩 (
GeocodeLocation): 지리적 좌표를 인간이 읽을 수 있는 상세 주소로 변환합니다. - 장소 지오코딩 (
GeocodePlace): 알려진 장소 ID의 형식화된 주소와 좌표를 찾습니다.
샘플 요청 및 응답
HTTP 인터페이스를 통해 Geocoding API에 액세스합니다. 다음은 목적지 검색, 정방향 지오코딩, 역 지오코딩의 빠른 시작 예시입니다.
목적지 검색 요청 및 응답 (세부 지역 도착 데이터)
다음 예에서는 '1600 Amphitheatre Parkway, Mountain View, CA'에 대해 HTTP POST 요청을 SearchDestinations에 전송합니다. SearchDestinations에는 반환할 필드를 지정하는 X-Goog-FieldMask 헤더가 필요합니다.
curl -X POST -d '{ "addressQuery": { "addressQuery": "1600 Amphitheatre Parkway, Mountain View, CA" } }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.formattedAddress,destinations.primary.location,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \ -H "X-Goog-Api-Key: YOUR_API_KEY" \ "https://geocode.googleapis.com/v4/geocode/destinations"
다음은 건물 윤곽선 다각형, 기본 출입구, 경로 지정 가능한 탐색 지점, 주변 명소를 보여주는 샘플 SearchDestinations 응답입니다.
{ "destinations": [ { "primary": { "displayName": { "text": "Googleplex", "languageCode": "en" }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "location": { "latitude": 37.4220656, "longitude": -122.0840897 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [-122.084958, 37.422145], [-122.084112, 37.422610], [-122.083510, 37.421980], [-122.084958, 37.422145] ] ] } }, "entrances": [ { "location": { "latitude": 37.422189, "longitude": -122.084215 }, "tags": ["PREFERRED"] } ], "navigationPoints": [ { "navigationPointToken": "Eg...", "displayName": { "text": "Amphitheatre Pkwy Dropoff", "languageCode": "en" }, "location": { "latitude": 37.421912, "longitude": -122.084301 }, "travelModes": ["DRIVE"], "usages": ["DROPOFF", "PICKUP"] } ], "landmarks": [ { "place": { "displayName": { "text": "Charleston Park", "languageCode": "en" } }, "relationalDescription": { "text": "Adjacent to Charleston Park", "languageCode": "en" }, "straightLineDistanceMeters": 85.4 } ] } ] }
지오코딩 요청 및 응답(위도/경도 검색)
다음 예에서는 '1600 Amphitheatre Parkway, Mountain View, CA'의 위도와 경도를 요청하고 출력이 JSON 형식이어야 한다고 지정합니다.
curl -H "X-Goog-Api-Key: YOUR_API_KEY" \ "https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
웹브라우저에 URL을 입력하여 이를 테스트할 수 있습니다(YOUR_API_KEY를 실제 API 키로 대체해야 함).
응답에는 이 주소의 위도와 경도가 포함됩니다.
지오코딩 요청 URL 빌드, 사용 가능한 매개변수, 응답 이해에 관한 자세한 내용은 개발자 가이드를 참고하세요.
다음은 JSON 형식의 샘플 지오코딩 응답입니다.
{ "results": [ { "place": "//places.googleapis.com/places/ChIJ2Z2idB66j4ARI43TG-9RoCQ", "placeId": "ChIJ2Z2idB66j4ARI43TG-9RoCQ", "location": { "latitude": 37.4438238, "longitude": -122.0869895 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.4424748197085, "longitude": -122.0883384802915 }, "high": { "latitude": 37.445172780291493, "longitude": -122.08564051970852 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043-1351", "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" ] }, { "longText": "1351", "shortText": "1351", "types": [ "postal_code_suffix" ] } ], "types": [ "premise", "street_address" ] } ] }
역지오코딩 요청 및 응답(주소 검색)
다음 예에서는 미국 뉴욕주 브루클린의 특정 위도/경도에 해당하는 주소를 요청합니다. 결과를 JSON 형식으로 출력하도록 지정합니다.
https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=YOUR_API_KEY웹브라우저에 URL을 입력하여 이를 테스트할 수 있습니다('YOUR_API_KEY'를 실제 API 키로 바꿔야 함). 응답에는 위도 및 경도 위치에 대해 사람이 읽을 수 있는 주소가 포함됩니다.
역 지오코딩 요청 URL 빌드, 사용 가능한 매개변수, 응답 이해에 관한 자세한 내용은 개발자 가이드를 참고하세요.
다음은 JSON 형식의 샘플 역지오코딩 응답입니다.
{ "results": [ { "place": "//places.googleapis.com/places/ChIJHRNUiQK6j4ARJ__Hrbt6qsE", "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE", "location": { "latitude": 37.4225657, "longitude": -122.08465439999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.421214719708509, "longitude": -122.08603273029148 }, "high": { "latitude": 37.423912680291508, "longitude": -122.0833347697085 } }, "bounds": { "low": { "latitude": 37.4225178, "longitude": -122.08484599999998 }, "high": { "latitude": 37.422609600000008, "longitude": -122.0845215 } }, "formattedAddress": "Google Building 40, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "Google Building 40", "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "Google Building 40", "shortText": "Google Building 40", "types": [ "premise" ], "languageCode": "en" }, { "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": [ "street_address", "subpremise" ] }, ... Additional results truncated in this example[] ... }
인증, 할당량, 가격 책정, 정책
인증
Geocoding API를 사용하려면 먼저 API를 사용 설정하고 적절한 사용자 인증 정보를 가져와야 합니다. 자세한 내용은 Google Maps Platform 시작하기를 참고하세요.
할당량 및 가격 책정
Geocoding API에 설정된 할당량 및 가격에 대한 자세한 내용은 사용량 및 결제 페이지를 참고하세요.
정책
Geocoding API는 API 정책에 따라 사용해야 합니다.