이 문서에서는 Places Insights API의 요청 매개변수를 설명하고 이 서비스를 사용하는 방법에 관한 통계 및 권장사항을 포함합니다.
Places Insights API를 사용하면 다음과 같은 몇 가지 주요 기능을 실행할 수 있습니다.
- 장소 수: 위치 유형, 운영 상태, 가격 수준, 평점과 같은 특정 기준과 일치하는 장소 수를 확인합니다.
- 장소 세부정보 가져오기: 지정된 필터를 충족하는 장소의 이름을 가져온 다음 Places API를 사용하여 더 자세한 정보를 가져옵니다.
- 유연한 필터링: 포괄적인 필터를 적용하여 정확한 통계를 얻을 수 있습니다.
사용 가능한 필터는 다음과 같습니다.
- 지리적 지역 (원, 지역 또는 맞춤 다각형)
- 장소 유형
- 영업 상태
- 가격 수준
- 평점 범위
필수 매개변수
이 섹션에서는 Places Insights API에 요청할 때 필요한 매개변수를 설명합니다. 각 요청은 다음을 제공해야 합니다.
- 통계 유형입니다.
- 위치 필터 및 유형 필터
통계 유형
계산할 통계 유형을 지정합니다. 다음과 같은 통계 유형이 지원됩니다.
INSIGHT_COUNT: 필터 기준과 일치하는 장소 수를 반환합니다.INSIGHT_PLACES: 필터 기준과 일치하는 장소 ID를 반환합니다.
필터
장소를 필터링하는 기준을 지정합니다. 최소한 LocationFilter 및 TypeFilter를 지정해야 합니다.
위치 필터
위치 필터는 다음 유형 중 하나일 수 있습니다.
circle: 중심과 반경이 있는 원으로 영역을 정의합니다.region: 영역을 지역으로 정의합니다.customArea: 영역을 맞춤 다각형으로 정의합니다.
원
지리적 지역을 원으로 선택하는 경우 center 및 radius을 제공해야 합니다. center는 위도와 경도 또는 원의 중심의 장소 ID일 수 있습니다. 이 메서드를 사용하면 정의된 원형 영역을 기반으로 정확하고 정밀하게 필터링할 수 있습니다.
center:latLng: 원의 중심의 위도 및 경도입니다. 위도는 -90과 90 사이의 숫자여야 합니다. 경도는 -180과 180 사이의 숫자여야 합니다(양 끝값 포함).place: 원 중심의 장소 ID입니다. 지점 장소만 지원됩니다. 이 문자열은places/접두사로 시작해야 합니다.
radius: 원의 반지름(단위: 미터)입니다. 이 숫자는 양수여야 합니다.
지역
장소 ID를 place 매개변수에 전달하여 지역을 정의합니다. 장소 ID는 지리적 영역 (예: 다각형으로 나타낼 수 있는 영역)을 나타냅니다. 예를 들어 플로리다주 탬파의 장소 ID는 places/ChIJ4dG5s4K3wogRY7SWr4kTX6c입니다. 일부 장소 ID에는 잘 정의된 도형이 없으며, 이 경우 Places Insights API는 지역이 지원되지 않는다는 메시지와 함께 400 오류 코드를 반환합니다. 또한 복잡한 지리적 지역의 경우 내부 처리 최적화로 인해 지역을 나타내는 영역이 약간 과대 추정될 수 있습니다 (최대 2~3%).
장소 ID가 지원되지 않는 장소 유형을 나타내는지 확인하려면 Geocoding API 요청에 장소 ID를 전달합니다. 응답에는 장소 ID와 연결된 장소 유형(예: city, neighborhood, country)을 나열하는 type 배열이 포함됩니다.
지원되지 않는 장소 유형은 다음과 같습니다.
establishment: 일반적으로 아직 분류되지 않은 장소를 나타냅니다.street_number: 정확한 번지를 나타냅니다.floor: 건물 주소의 층을 나타냅니다.post_box: 특정 우편함을 나타냅니다.street_address: 정확한 상세 주소를 나타냅니다.room: 건물 주소의 방을 나타냅니다.intersection: 일반적으로 두 주요 도로의 주요 교차로를 나타냅니다.landmark: 탐색을 돕기 위해 참조로 사용되는 주변 장소를 나타냅니다.subpremise: 아파트, 객실, 스위트와 같이 건물 수준 아래의 주소 지정이 가능한 항목을 나타냅니다.sublocality_level_5: 가장 구체적인 하위 지역 주소 구성요소 수준입니다. 일반적으로 매우 작은 동네 하위 구역 또는 도시 내의 하이퍼로컬 지역을 나타냅니다.
맞춤 영역
위도 및 경도 좌표를 사용하여 맞춤 다각형의 면적을 정의합니다.
https://geojson.io/에서 맞춤 다각형을 그리고 요청에 해당 좌표를 입력할 수 있습니다. 다각형은 첫 번째 좌표와 마지막 좌표가 동일한 최소 4개의 좌표를 가져야 합니다. 제공된 좌표 중 3개 이상은 고유해야 합니다.
연속적으로 동일한 좌표는 단일 좌표로 취급됩니다. 그러나 연속되지 않은 중복 좌표 (필수 동일한 첫 번째 및 마지막 좌표 제외)는 오류를 초래합니다.
또한 인접하지 않은 가장자리가 교차할 수 없으며 길이가 180도인 가장자리도 허용되지 않습니다. 즉, 인접한 정점이 지구 반대편에 있을 수 없습니다.
예를 들면 다음과 같습니다.
"coordinates":[ { "latitude":37.776, "longitude":-122.666 }, { "latitude":37.130, "longitude":-121.898 }, { "latitude":37.326, "longitude":-121.598 }, { "latitude":37.912, "longitude":-122.247 }, { "latitude":37.776, "longitude":-122.666 } ]
유형 필터
포함하거나 제외할 장소 유형을 지정합니다. Places Insights API에서 지원하는 기본 및 보조 장소 유형 목록은 Places API(신규)의 장소 유형에 있는 표 A를 참고하세요. includedTypes 또는 includedPrimaryTypes 유형을 하나 이상 지정해야 합니다.
includedTypes: 포함된 장소 유형 목록입니다.excludedTypes: 제외된 장소 유형 목록입니다.includedPrimaryTypes: 포함된 기본 장소 유형 목록입니다.excludedPrimaryTypes: 제외된 기본 장소 유형 목록입니다.
유형 필터 및 장소 유형의 작동 방식에 대해 자세히 알아보려면 유형 필터에 관한 자세한 내용을 참고하세요.
선택적 매개변수
다음 필터는 선택사항입니다.
operatingStatus: 포함하거나 제외할 장소의 상태를 지정합니다. 기본값은operatingStatus: OPERATING_STATUS_OPERATIONAL(특정 값 1개)로 필터링됩니다.priceLevels: 장소의 가격 수준을 지정합니다. 기본값은 필터링 없음입니다 (모든 가격 수준이 결과에 포함됨).ratingFilter: 장소의 평점 범위를 지정합니다. 기본값은 필터링 없음입니다 (모든 평점이 결과에 포함됨).
영업 상태
operatingStatus 필터를 사용하면 운영 상태(예: 영업 중 또는 임시 휴업)를 기준으로 필터링할 수 있습니다. operatingStatus 필터가 설정되지 않으면 운영 상태가 OPERATING_STATUS_OPERATIONAL인 장소만 결과에 포함됩니다.
가격 수준
price_levels 필터를 사용하면 가격 수준 (예: 무료, 적당함, 비싸움)을 기준으로 필터링할 수 있습니다. price_levels 필터가 설정되지 않으면 모든 가격대가 결과에 포함됩니다.
평점 필터
평균 사용자 평점을 기준으로 장소를 필터링합니다. 이 두 필드는 선택사항이므로 생략하면 평점이 없는 장소도 기본적으로 포함됩니다.
minRating: 최소 평균 사용자 평점 (1.0~5.0)maxRating: 최대 평균 사용자 평점 (1.0~5.0)입니다.
또한 minRating 값은 항상 maxRating 값보다 작거나 같아야 합니다. minRating가 maxRating보다 크도록 지정하면 INVALID_ARGUMENT 오류가 반환됩니다.