Google Play App Rankings
Google Play 차트 URL은 수집할 카테고리 또는 순위 화면을 지정하고, results_limit은 1에서 2000건까지 탐색 깊이를 정합니다. 저장되는 결과는 모두 AppItem 사양을 따르므로, 순위를 확인 가능한 패키지 식별 정보, 개발자, 카테고리, 평점, 리뷰 수, 설치 수, 가격, 미디어, 원본 URL, 수집 시각과 함께 분석할 수 있습니다.
Google Play App Rankings API 주요 기능
- 차트 URL 일괄 처리국가나 카테고리를 별도 필드로 넣는 대신, 공개 play.google.com 카테고리 또는 순위 페이지로 이루어진, 비어 있지 않은 urls 배열을 제출합니다.
- Google Play 순위 URL 검증런타임은 경로에 /store/apps/collection/ 또는 /store/apps/category/가 포함된 경우에만 play.google.com과 그 서브도메인을 허용합니다.
- 범위가 정해진 순위 수집results_limit은 1 이상 2000 이하로 지정합니다. 생략하면 100이 적용되며, 이 값은 예상 요금과 제공처 탐색 기본값이기도 합니다.
- 정규화된 앱 순위rank를 확인 가능한 app_id, name, developer, category, rating, reviews_count, installs, price, media, 공개 원본 메타데이터와 함께 하나의 AppItem 구조로 읽습니다.
- 비동기 데이터셋 워크플로제출한 URL 행이 비동기 제공처 데이터셋을 실행하고, SocQ는 정규화된 레코드를 저장하며 공용 작업 조회기를 통해 작업 상태를 반환합니다.
- 저장된 결과 커서성공 후에는 작업 조회기의 불투명한 next_cursor와 1~500 사이의 limit으로 SocQ 레코드를 페이지네이션합니다. 이 커서는 Google Play나 제공처의 페이지 토큰이 아닙니다.
- 실제 결과 기준 정산SocQ는 요청한 값 또는 기본 예상 결과 수만큼 먼저 차감한 뒤, 저장된 결과 1건당 0.15 크레딧으로 정산하고 사용하지 않은 예상 크레딧은 환불합니다. 결과가 비어 있으면 기본 요금 0 크레딧으로 정산됩니다.
Google Play App Rankings API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
urls | 필수 | 공개 Google Play 순위 URL의 배열로, 비어 있지 않아야 하는 필수 값입니다. 모든 URL은 play.google.com 또는 그 서브도메인을 사용하고 경로에 /store/apps/collection/ 또는 /store/apps/category/가 포함되어야 하며, 런타임은 국가나 카테고리를 독립된 필드로 받지 않습니다. |
results_limit | 선택 | 1 이상 2000 이하의 양의 정수이며, 선택 값입니다. 기본값은 100이고, 작업 전체에서 탐색과 저장 레코드의 상한을 정하며 초기 예상 요금의 기준이 됩니다. 입력 URL은 순서대로 작업의 남은 할당량을 기준으로 처리됩니다. |
Google Play App Rankings API 사용 방법
알고 있는 Google Play 차트 URL을 하나 이상 제출하고, 비동기 작업을 따라간 뒤, 성공하면 정규화된 순위 레코드를 읽습니다.
- 필요한 시장과 수집 화면이 차트 컨텍스트에 이미 담겨 있는 공개 play.google.com 카테고리 또는 순위 URL을 고릅니다.
- urls와 선택 항목인 results_limit을 /v1/google-play/app-rankings로 POST하고, 반환된 task_id를 저장합니다.
- status가 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다. 작업이 대기 중이거나 실행 중인 동안에는 결과를 읽을 수 없습니다.
- data.results.items를 읽고, has_more가 true일 때만 next_cursor로 이어서 가져옵니다.
curl -X POST "https://api.socq.ai/v1/google-play/app-rankings" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://play.google.com/store/apps/collection/topselling_free"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Continue with GET /v1/tasks/{task_id}?cursor={next_cursor}&limit=50Google Play App Rankings API 추천 활용 사례
- 카테고리 차트 스냅샷: rank와 collected_at을 함께 저장해, 알고 있는 Google Play 차트를 따로 수집한 스냅샷끼리 비교합니다.
- 순위 기반 앱 발굴: 엄선한 카테고리 URL 묶음을 정규화된 앱 레코드로 바꿔 검토, 태깅 또는 이후 카탈로그 정보 보강에 사용합니다.
- 포트폴리오 순위 확인: 확인 가능한 app_id와 developer 필드를 내부 포트폴리오와 매칭한 뒤, 표시 이름 일치에만 의존하지 않고 반환된 순위를 하나씩 살펴봅니다.
- 수집 회차 간 스토어 분석: 고정된 AppItem 필드를 데이터 웨어하우스에 적재해 null 가능한 평점, 리뷰 수, 설치 수, 가격, 순위를 수집 회차 간에 비교할 수 있게 유지합니다.
Google Play App Rankings API 활용 팁
- 앱 상세 페이지, 검색어, 국가 코드, 카테고리 이름이 아니라 공개 Google Play 카테고리 또는 차트 URL을 사용하세요. 이 요청에는 urls와 results_limit만 들어갑니다.
- 경로에 /store/apps/collection/ 또는 /store/apps/category/가 포함된 play.google.com URL을 사용하세요. 앱 상세 페이지나 관련 없는 경로는 수집이 시작되기 전에 검증에서 실패합니다.
- 입력 URL이 여러 개일 때 results_limit은 작업 전체가 공유합니다. URL은 순서대로 처리되며 각 URL은 남은 할당량만 받으므로, 차트마다 독립된 할당량이 필요하면 작업을 나누세요.
- 앱 메타데이터는 null일 수 있다고 가정하세요. 평점, 리뷰 수, 설치 수, 가격, 미디어가 항상 채워진다고 단정하지 말고, 확인 가능한 app_id, url, rank, collected_at을 보존하세요.
- 원본 커서는 보내지 마세요. 성공할 때까지 기다린 뒤, data.results 안에 반환된 불투명한 next_cursor만으로 SocQ에 저장된 레코드를 페이지네이션하세요.
- 제출 시점의 results_limit을 기준으로 예산을 잡으세요. 최종 크레딧은 실제로 저장된 결과 수에 건당 0.15 크레딧을 곱한 값이며, 사용하지 않은 예상 크레딧은 환불됩니다.
관련 API
Google Play App Rankings API 외에 Google Play의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Google Play App Detail API — 알고 있는 앱 URL에서 정규화된 공개 Google Play 등록 정보를 가져오며, 앱 정보, 스토어 문구, 개발자, 카테고리, 공개된 지표, 가격, 미디어, 수집 맥락을 포함합니다.
- Google Play App Reviews API — play.google.com URL에서 공개 앱 리뷰를 수집하며, 선택적인 국가 맥락과 정규화된 텍스트, 리뷰어, 평점, 시각, 앱 참조 필드를 포함합니다.