Destination은 사용자가 도달하거나 이동하려는 중요한 관심 장소 또는 특정 위치를 나타냅니다. Destination에는 탐색 지점, 랜드마크, 입구, 건물 개요와 같은 정보가 포함될 수 있습니다.
Geocoding API의 SearchDestinations 엔드포인트를 사용하면 주소, 장소 ID, 위도 및 경도 좌표와 같은 다양한 입력 기준에 따라 여러 목적지에 관한 세부정보를 가져올 수 있습니다.
목적지 검색 요청
검색 대상 요청은 다음 형식의 URL에 대한 HTTP POST 요청입니다.
https://geocode.googleapis.com/v4alpha/geocode/destinations
JSON 요청 본문 또는 헤더에서 POST 요청의 일부로 모든 매개변수를 전달합니다. 예를 들면 다음과 같습니다.
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
다음 3가지 방법 중 하나로 목적지를 검색할 위치를 지정할 수 있습니다.
- 주소
- 장소 ID
- 위도 및 경도 좌표
주소로 목적지 검색
주소를 구조화되지 않은 문자열로 지정할 수 있습니다.
curl -X POST -d '{
"addressQuery": {
"addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
또는 postalAddress로:
curl -X POST -d '{
"addressQuery": {
"address": {
"addressLines": ["601 S Bernardo Ave"],
"locality": "Sunnyvale",
"postalCode": "94087",
"administrativeArea": "CA",
"regionCode": "US"
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
일반적으로 HTML 양식에서 캡처된 주소 구성요소를 처리할 때는 postalAddress 형식을 사용합니다.
장소 ID로 목적지 검색
장소 ID를 제공하여 목적지를 검색할 수 있습니다.
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
위치로 목적지 검색
위도 및 경도 좌표를 제공하여 목적지를 검색할 수 있습니다.
curl -X POST -d '{
"locationQuery": {
"location": {
"latitude": 37.37348780,
"longitude": -122.05678064
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
OAuth를 사용하여 요청하기
Geocoding API v4는 인증을 위해 OAuth 2.0을 지원합니다. Geocoding API에서 OAuth를 사용하려면 OAuth 토큰에 올바른 범위가 할당되어야 합니다. Geocoding API는 Destinations 엔드포인트와 함께 사용할 수 있는 다음 범위를 지원합니다.
https://www.googleapis.com/auth/maps-platform.geocode— 모든 Geocoding API 엔드포인트와 함께 사용합니다.
또한 모든 Geocoding API 엔드포인트에 일반 https://www.googleapis.com/auth/cloud-platform 범위를 사용할 수 있습니다. 이 범위는 모든 엔드포인트에 대한 액세스를 허용하는 일반 범위이므로 개발 중에는 유용하지만 프로덕션에서는 유용하지 않습니다.
자세한 내용과 예는 OAuth 사용을 참고하세요.
목적지 검색 응답
SearchDestinations는 SearchDestinationsResponse를 반환합니다.
전체 JSON 객체는 다음 형식입니다.
{ "destinations": [ { "primary": { "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w", "displayName": { "text": "Arby's", "languageCode": "en" }, "primaryType": "fast_food_restaurant", "types": [ "fast_food_restaurant", "sandwich_shop", "deli", "american_restaurant", "meal_takeaway", "restaurant", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "601 S Bernardo Ave" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3734545, "longitude": -122.05693269999998 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.056930138027, 37.3735253692531 ], [ -122.056960139391, 37.3735372663597 ], [ -122.056994129366, 37.3734828786847 ], [ -122.056969677395, 37.3734731161089 ], [ -122.057061762447, 37.3733261309656 ], [ -122.056979388817, 37.3732935577128 ], [ -122.056798860285, 37.3735818838642 ], [ -122.056875858081, 37.3736121235316 ], [ -122.056930138027, 37.3735253692531 ] ] ] } }, "containingPlaces": [ { "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw", "displayName": { "text": "Cherry Chase Shopping Center", "languageCode": "en" }, "primaryType": "shopping_mall", "types": [ "shopping_mall", "point_of_interest", "establishment" ], "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1020", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "663 S Bernardo Ave" ] }, "structureType": "GROUNDS", "location": { "latitude": 37.3731231, "longitude": -122.0578211 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.057112227103, 37.3714618008523 ], [ -122.057076849821, 37.3715743611411 ], [ -122.056963607756, 37.3719081793948 ], [ -122.056865279559, 37.3722026053835 ], [ -122.056687872374, 37.3727258358476 ], [ -122.056580005889, 37.3730511370747 ], [ -122.056498845827, 37.3732994782583 ], [ -122.056338259713, 37.3737878663325 ], [ -122.056618678291, 37.373887693582 ], [ -122.056912102521, 37.3740010327191 ], [ -122.057532418159, 37.3742476426462 ], [ -122.057673926626, 37.3742441740031 ], [ -122.057735663106, 37.3742328516943 ], [ -122.057766531332, 37.3742220604378 ], [ -122.057797572967, 37.37420520725 ], [ -122.057828267759, 37.3741852342085 ], [ -122.058060299297, 37.3740060842535 ], [ -122.058199726081, 37.3737861673422 ], [ -122.05836707267, 37.373524542556 ], [ -122.058569622393, 37.3732018598683 ], [ -122.0587638478, 37.3728890198039 ], [ -122.058934661823, 37.3726036257774 ], [ -122.059164956851, 37.3722498383629 ], [ -122.058997784906, 37.3721804442035 ], [ -122.057936479838, 37.3717605636234 ], [ -122.057495827092, 37.3715860151634 ], [ -122.057112227103, 37.3714618008523 ] ] ] } } ], "landmarks": [ { "place": { "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14", "displayName": { "text": "Safeway", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "florist", "butcher_shop", "deli", "bakery", "food_delivery", "supermarket", "market", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "639 S Bernardo Ave" ] }, "structureType": "POINT", "location": { "latitude": 37.3727912, "longitude": -122.0581172 } }, "tags": [ "ARRIVAL", "ADDRESS" ] }, { "place": { "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs", "displayName": { "text": "Starbird Chicken", "languageCode": "en" }, "types": [ "fast_food_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1028", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1241 W El Camino Real" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3746764, "longitude": -122.05708860000001 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.057003840785, 37.3747648209809 ], [ -122.057136852459, 37.3747919153144 ], [ -122.057205005705, 37.3745815131859 ], [ -122.057071994114, 37.3745544186944 ], [ -122.057003840785, 37.3747648209809 ] ] ] } }, "tags": [ "ARRIVAL", "ADDRESS" ] }, { "place": { "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg", "displayName": { "text": "Chase Bank", "languageCode": "en" }, "primaryType": "bank", "types": [ "bank", "atm", "finance", "point_of_interest", "establishment" ], "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1234 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.373579, "longitude": -122.05752700000001 } }, "tags": [ "ARRIVAL", "ADDRESS" ] }, { "place": { "place": "places/ChIJlbIO1Oi2j4ARp17Uf24xkHk", "displayName": { "text": "Madras Café", "languageCode": "en" }, "primaryType": "indian_restaurant", "types": [ "indian_restaurant", "coffee_shop", "cafe", "restaurant", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Madras Café, 1177 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1026", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1177 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3743, "longitude": -122.0549333 } }, "tags": [ "ARRIVAL", "ADDRESS" ] } ], "entrances": [ { "location": { "latitude": 37.373531299999996, "longitude": -122.05694519999999 }, "tags": [ "PREFERRED" ], "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w" } ], "navigationPoints": [ { "location": { "latitude": 37.3738659, "longitude": -122.05693620000001 }, "travelModes": [ "DRIVE", "WALK" ], "usages": [ "UNKNOWN" ] } ] } ] }
필수 매개변수
- 다음 3가지 매개변수 중 하나가 API 요청에 있어야 합니다. 이 매개변수는 목적지를 검색할 주소, 장소 또는 위치를 지정합니다.
addressQuery- 검색할 주소입니다.place- 검색할 장소의 장소 ID입니다.locationQuery- 검색할 위치의 위도 및 경도 좌표입니다.
FieldMask
응답 필드 마스크를 만들어 응답에서 반환할 필드의 목록을 지정합니다. URL 매개변수
$fields또는fields를 사용하거나 HTTP 헤더X-Goog-FieldMask를 사용하여 응답 필드 마스크를 메서드에 전달합니다. 예를 들어 아래 요청은 기본 목적지의 출입구, 탐색 지점, 장소 ID만 반환합니다.curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \ -H "X-Goog-Api-Key: API_KEY" \ -H "Content-Type: application/json" \ -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \ https://geocode.googleapis.com/v4alpha/geocode/destinations응답에 반환된 필드의 기본 목록이 없습니다. 필드 마스크를 생략하면 메서드에서 오류를 반환합니다. 모든 필드를 반환하려면 필드 마스크를
*로 설정합니다. 자세한 내용은 반환할 필드 선택을 참고하세요.
선택적 매개변수
-
travelModes
반환할
navigationPoints유형을 지정합니다. 다른 이동 수단의 탐색 포인트는 필터링으로 제외됩니다.travelModes가 설정되지 않은 경우 모든 이동 수단의 탐색 지점이 반환될 수 있습니다. languageCode
결과를 반환할 언어입니다.
- 지원되는 언어 목록을 참고하세요. Google에서는 지원되는 언어를 자주 업데이트하므로 이 목록에 모든 언어가 포함되지 않을 수도 있습니다.
-
languageCode가 제공되지 않으면 API는 기본적으로en을 사용합니다. 잘못된 언어 코드를 지정하면 API에서INVALID_ARGUMENT오류를 반환합니다. - API는 사용자와 현지인 모두가 읽을 수 있는 상세 주소를 제공하기 위해 최선을 다합니다. 이 목표를 달성하기 위해 선호하는 언어를 준수하여 필요한 경우 사용자가 읽을 수 있는 스크립트로 음역된 현지 언어의 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
- 선호하는 언어로 이름을 사용할 수 없는 경우 API는 가장 일치하는 이름을 사용합니다.
- 기본 언어는 API가 반환하도록 선택한 결과 집합과 반환되는 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 약어를 다르게 해석합니다. 예를 들어 거리 유형의 약어나 한 언어에서는 유효하지만 다른 언어에서는 유효하지 않은 동의어가 있습니다.
regionCode
두 자리 CLDR 코드 값으로 된 지역 코드입니다. 기본값은 없습니다. 대부분의 CLDR 코드는 ISO 3166-1 코드와 동일합니다.
주소를 지오코딩할 때(정방향 지오코딩) 이 매개변수는 서비스의 결과를 지정된 지역으로 제한하지는 않지만 영향을 줄 수 있습니다. 위치 또는 장소를 지오코딩할 때(역 지오코딩 또는 장소 지오코딩) 이 매개변수를 사용하여 주소 형식을 지정할 수 있습니다. 모든 경우에 이 매개변수는 관련 법규에 따라 결과에 영향을 줄 수 있습니다.
의견
이는 Geocoding API의 실험용 엔드포인트입니다. geocoding-feedback-channel@google.com으로 의견을 보내 주시면 감사하겠습니다.