Apple App Store Rankings
Apple App Store 카테고리 순위는 순위, 앱 식별 정보, 개발자, 카테고리, 평점, 리뷰 수, 가격, 아트워크 필드를 갖춘 순서가 있는 공개 앱 목록입니다. 이러한 레코드는 차트 모니터링, 순위가 포함된 카탈로그 정보 보강, 각 순위에 붙은 공개 스토어 정보 비교에 활용할 수 있습니다.
Apple App Store Rankings API 주요 기능
- 카테고리 차트 URL 탐색공개 apps.apple.com 카테고리 또는 순위 URL을 하나 이상 탐색 입력으로 사용해, 해당 페이지에 노출되는 순위별 앱 레코드를 가져옵니다.
- 순위와 앱 식별 정보확인 가능한 원본 순위를 앱 ID, 이름, 공개 스토어 URL과 함께 유지해 순서가 있는 결과도 구분할 수 있게 합니다.
- 개발자·카테고리 정보확인 가능한 개발자 또는 퍼블리셔 이름과 스토어 카테고리를 정규화된 앱 레코드마다 반환합니다.
- 공개된 스토어 지표공개 차트 결과에 노출되는 경우 평점, 리뷰 수, 구조화된 가격 값을 포함합니다.
- 설명과 아트워크확인 가능한 앱 텍스트와 미디어 참조를 나머지 결과와 동일한 고정 앱 스키마로 보존합니다.
Apple App Store Rankings API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
urls | 필수 | 공개 Apple App Store 순위 URL의 필수 배열입니다. 파싱된 호스트 이름은 모두 apps.apple.com 또는 그 서브도메인이어야 하며, 모든 경로에 /charts/가 포함되어야 합니다. |
results_limit | 선택 | 작업 전체에 적용되는 1~2,000 범위의 상한이며 선택 항목입니다. 이 필드를 생략하면 백엔드는 100을 사용합니다. |
Apple App Store Rankings API 사용 방법
공개 Apple App Store 카테고리 차트 URL로 시작해 전체 결과 상한을 정하고, 작업이 성공하면 저장된 정규화된 앱 레코드를 읽습니다.
- 경로에 /charts/가 포함된 공개 apps.apple.com 순위 URL을 하나 이상 입력합니다. 제공된 샘플은 백엔드 검증 규칙을 충족합니다.
- results_limit을 1~2,000 범위에서 설정하거나, 생략해 백엔드 기본값인 100건을 사용합니다.
- 페이로드를 /v1/apple-app-store/rankings로 POST하고 task_id를 저장한 뒤, 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽고, has_more가 true인 동안 next_cursor로 저장된 다음 결과 페이지를 요청합니다.
curl -X POST "https://api.socq.ai/v1/apple-app-store/rankings" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://apps.apple.com/us/iphone/charts/6007"],"results_limit":3}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueApple App Store Rankings API 추천 활용 사례
- 카테고리 차트 모니터링: 반복 실행에서 얻은 순위, 앱 식별 정보, collected_at을 저장해 특정 시점의 차트 스냅샷을 구분합니다.
- 순위 포함 앱 카탈로그 정보 보강: 차트에서 발견한 항목에 앱 ID, 이름, 개발자, 카테고리, 스토어 URL, 설명, 아트워크를 추가합니다.
- 스토어 정보 비교: 같은 카테고리 차트에서 반환된 앱들의 순위, 평점, 리뷰 수, 가격 필드를 비교합니다.
Apple App Store Rankings API 활용 팁
- 경로에 /charts/가 포함된 apps.apple.com 순위 URL을 사용하세요. 개별 앱 상세 URL이나 관련 없는 경로는 수집이 시작되기 전에 검증에서 실패합니다.
- urls에 차트를 여러 개 넣어도 results_limit은 작업 전체에 저장되는 행 수를 제한하므로, 차트마다 별도 할당량이 필요하면 작업을 나누어 제출하세요.
- next_cursor는 저장된 SocQ 결과를 페이지 단위로 넘길 때만 사용하세요. 다른 공급자 차트 페이지를 요청하거나 처음 정한 결과 상한을 늘리지 않습니다.
- 작업은 저장된 레코드를 앱 ID 또는 원본 URL 기준으로 중복 제거하므로, 겹치는 차트에서 모든 차트별 노출을 보존해야 한다면 차트를 따로 실행하세요.
- 설명, 평점, 리뷰 수, 가격, 아트워크 등 선택 필드는 null일 수 있는 값으로 취급하고, 이후 화면에서는 빈 값을 표시하지 마세요.
관련 API
Apple App Store Rankings API 외에 Apple App Store의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Apple App Store App Detail API — 알고 있는 App Store 등록 URL에서 정규화된 공개 앱 정보, 설명 메타데이터, 개발자 및 카테고리 맥락, 공개된 평점, 가격, 미디어를 가져옵니다.
- Apple App Store App Reviews API — 알고 있는 apps.apple.com URL에서 공개 앱 리뷰를 수집하며, 정규화된 텍스트, 평점, 리뷰어 정보, 타임스탬프, 앱 참조를 포함합니다.