장소 ID가 있으면 장소 세부정보 (신규) 요청을 실행하여 특정 시설이나 관심 지점에 대한 추가 세부정보를 요청할 수 있습니다. 장소 세부정보 (신규) 요청은 전체 주소, 전화번호, 사용자 평점, 리뷰와 같이 지정된 장소에 대한 더 포괄적인 정보를 반환합니다.
장소 ID를 가져오는 방법에는 여러 가지가 있습니다. 이 옵션은 다음과 같습니다.
- 텍스트 검색 (신규) 또는 Nearby Search (신규)
- Geocoding API
- Routes API
- Address Validation API
- Place Autocomplete
API 탐색기를 사용하면 실시간 요청을 수행하여 API 및 API 옵션에 익숙해질 수 있습니다.
사용해 보기장소 세부정보 (신규) 요청
장소 세부정보 요청은 다음 형식의 HTTP GET 요청입니다.
https://places.googleapis.com/v1/places/PLACE_ID
모든 매개변수를 URL 매개변수로 전달하거나 GET 요청의 일부로 헤더에 전달합니다. 예를 들면 다음과 같습니다.
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY또는 cURL 명령어에서 다음을 실행합니다.
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
장소 세부정보 (신규) 응답
Place Details (New)는 JSON 객체를 응답으로 반환합니다. 응답에서 각 항목의 의미는 다음과 같습니다.
- 응답은
Place객체로 표현됩니다.Place객체에는 장소에 관한 자세한 정보가 포함됩니다. - 요청에 전달된 FieldMask는
Place객체에서 반환되는 필드 목록을 지정합니다.
전체 JSON 객체는 다음과 같은 형식입니다.
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
필수 매개변수
-
FieldMask
응답 필드 마스크를 만들어 응답에서 반환할 필드 목록을 지정합니다. URL 매개변수
$fields또는fields를 사용하거나 HTTP 헤더X-Goog-FieldMask를 사용하여 응답 필드 마스크를 메서드에 전달합니다. 응답에는 반환된 필드의 기본 목록이 없습니다. 필드 마스크를 생략하면 메서드가 오류를 반환합니다.필드 마스크는 불필요한 데이터의 요청을 방지하여 불필요한 처리에 드는 시간과 요금을 막을 수 있는 좋은 설계 방법입니다.
반환할 장소 데이터 유형의 쉼표로 구분된 목록을 지정합니다. 예를 들어 장소의 표시 이름과 주소를 가져옵니다.
X-Goog-FieldMask: displayName,formattedAddress
*를 사용하여 모든 필드를 가져옵니다.X-Goog-FieldMask: *
다음 필드 중 하나 이상을 지정합니다.
다음 필드는 Place Details (IDs Only) SKU를 트리거합니다.
attributions,id,name*,photos
*name필드에 리소스 이름 장소가places/PLACE_ID형식으로 포함됩니다.displayName을 사용하여 장소의 텍스트 이름에 액세스합니다.다음 필드는 Place Details (Location Only) SKU를 트리거합니다.
addressComponents,adrFormatAddress,formattedAddress,location,plusCode,shortFormattedAddress,types,viewport다음 필드는 Place Details (Basic) SKU를 트리거합니다.
accessibilityOptions,businessStatus,containingPlaces,displayName,googleMapsLinks*,googleMapsUri,iconBackgroundColor,iconMaskBaseUri,primaryType,primaryTypeDisplayName,pureServiceAreaBusiness,subDestinations,utcOffsetMinutes
*googleMapsLinks필드는 GA 이전 미리보기 단계에 있으며 요금이 청구되지 않습니다. 즉, 미리보기 기간 동안 사용 시 청구 금액은 0달러입니다.다음 필드는 Place Details (Advanced) SKU를 트리거합니다.
currentOpeningHours,currentSecondaryOpeningHours,internationalPhoneNumber,nationalPhoneNumber,priceLevel,priceRange,rating,regularOpeningHours,regularSecondaryOpeningHours,userRatingCount,websiteUri다음 필드는 Place Details (Preferred) SKU를 트리거합니다.
allowsDogs,curbsidePickup,delivery,dineIn,editorialSummary,evChargeOptions,fuelOptions,goodForChildren,goodForGroups,goodForWatchingSports,liveMusic,menuForChildren,parkingOptions,paymentOptions,outdoorSeating,reservable,restroom,reviews,routingSummaries,*servesBeer,servesBreakfast,servesBrunch,servesCocktails,servesCoffee,servesDessert,servesDinner,servesLunch,servesVegetarianFood,servesWine,takeout
* 텍스트 검색 및 주변 검색만 해당
-
placeId
장소를 고유하게 식별하는 텍스트 식별자이며, 텍스트 검색 (신규) 또는 주변 지역 검색 (신규)에서 반환됩니다. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참고하세요.
문자열
places/PLACE_ID는 장소 리소스 이름이라고도 합니다. Place Details (신규), Nearby Search (신규), Text Search (신규) 요청의 응답에서 이 문자열은 응답의name필드에 포함됩니다. 독립형 장소 ID는 응답의id필드에 포함됩니다.
선택적 매개변수
languageCode
결과를 반환할 언어입니다.
- 지원 언어 목록을 참고하세요. 지원되는 언어는 자주 업데이트되므로 목록이 완전하지 않을 수 있습니다.
-
languageCode가 제공되지 않으면 API의 기본값은en입니다. 잘못된 언어 코드를 지정하면 API에서INVALID_ARGUMENT오류를 반환합니다. - API는 사용자와 현지인이 모두 읽을 수 있는 거리 주소를 제공하려고 최선을 다합니다. 이를 위해 API는 기본 언어를 준수하면서 필요한 경우 사용자가 읽을 수 있는 스크립트로 음차한 현지 언어로 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
- 기본 언어로 이름을 사용할 수 없는 경우 API는 가장 유사한 일치 항목을 사용합니다.
- 기본 언어는 API가 반환하려고 선택한 결과 집합과 반환 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 유효하거나 유효하지 않을 수 있는 동의어 또는 거리 유형에 대한 약어와 같이 언어에 따라 다르게 약어를 해석합니다.
regionCode
응답 형식을 지정하는 데 사용되는 지역 코드로, 2자리 CLDR 코드 값으로 지정됩니다. 기본값은 없습니다.
응답의
formattedAddress필드의 국가 이름이regionCode와 일치하는 경우 국가 코드는formattedAddress에서 생략됩니다. 이 매개변수는 국가 이름을 항상 포함하는adrFormatAddress에는 영향을 미치지 않으며 국가 이름을 포함하지 않는shortFormattedAddress에는 영향을 미치지 않습니다.대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 눈에 띄는 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk'(.co.uk)이지만 ISO 3166-1 코드는 'gb'(기술적으로 '영국 및 북아일랜드' 엔티티)입니다. 매개변수는 관련 법률에 따라 결과에 영향을 미칠 수 있습니다.
-
sessionToken
세션 토큰은 Autocomplete(신규) 호출을 '세션'으로 추적하는 사용자 생성 문자열입니다. 자동 완성 (신규)은 세션 토큰을 사용하여 사용자 자동 완성 검색의 쿼리 및 장소 선택 단계를 결제 목적의 개별 세션으로 그룹화합니다. 세션 토큰은 Autocomplete (신규) 호출 다음에 오는 Place Details (신규) 호출에 전달됩니다. 자세한 내용은 세션 토큰을 참고하세요.
장소 세부정보 예시
다음 예에서는 placeId를 사용하여 장소 세부정보를 요청합니다.
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
X-Goog-FieldMask 헤더는 응답에 id,displayName 데이터 필드가 포함되어 있음을 지정합니다.
응답은 다음과 같은 형식입니다.
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" } }
추가 정보를 반환하려면 필드 마스크에 데이터 유형을 더 추가하세요.
예를 들어 formattedAddress,plusCode를 추가하여 응답에 주소와 Plus Code를 포함합니다.
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
이제 응답의 형식은 다음과 같습니다.
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "plusCode": { "globalCode": "849VCWC7+RW", "compoundCode": "CWC7+RW Mountain View, CA, USA" }, "displayName": { "text": "Googleplex", "languageCode": "en" } }
사용해 보기
API 탐색기를 사용하면 샘플 요청을 실행하여 API 및 API 옵션을 익힐 수 있습니다.
요청하려면 다음 단계를 따르세요.
- 페이지 오른쪽에 있는 API 아이콘
을 선택합니다. - 필요한 경우
name매개변수를 다음과 같이 설정합니다.places/PLACE_ID - 필요한 경우 표준 매개변수 표시를 펼치고
fields매개변수를 필드 마스크로 설정합니다. - 실행 버튼을 선택합니다. 팝업에서 요청에 사용할 계정을 선택합니다.
API 탐색기 패널에서 확장 아이콘
을 선택하여 API 탐색기 창을 펼칩니다.