Apple App Store Rankings API

Apple App Store Rankings

Features

• Category chart URL discoveryUse one or more public apps.apple.com category or ranking URLs as discovery inputs for the ranked app records exposed by those pages.
• Position and app identityKeep each available source rank beside the app ID, name, and public store URL so ordered results remain identifiable.
• Developer and category contextReturn the available developer or publisher name and store category with each normalized application record.
• Visible store signalsInclude rating, review count, and structured price values when the public chart result exposes them.
• Descriptions and artworkPreserve available app text and media references in the same fixed app schema used for the rest of the result.

Parameters

How to Use

Start with a public Apple App Store category chart URL, set the overall result cap, and read the saved normalized app records after the task succeeds.

1. Enter one or more public apps.apple.com ranking URLs whose path contains /charts/; the provided sample satisfies the backend validation rule.
2. Set results_limit from 1 to 2,000, or omit it to use the backend default of 100 results.
3. POST the payload to /v1/apple-app-store/rankings, save task_id, and poll /v1/tasks/{task_id} until the task succeeds or fails.
4. Read data.results.items and request the next stored result page with next_cursor while has_more is true.

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 true

Best Use Cases

• Category chart monitoring: Store rank, app identity, and collected_at from repeated runs to distinguish point-in-time chart snapshots.
• Ranked app catalog enrichment: Attach app IDs, names, developers, categories, store URLs, descriptions, and artwork to entries discovered in a chart.
• Store context comparison: Compare available rank, rating, review count, and price fields across apps returned from the same category chart.

Pro Tips

• Use an apps.apple.com ranking URL whose path contains /charts/. Individual app detail URLs and unrelated paths fail validation before collection starts.
• Submit separate tasks when every chart needs its own quota, because results_limit caps the total rows saved for the task even when urls contains several charts.
• Follow next_cursor only to page stored SocQ results; it does not request another provider chart page or extend the original result cap.
• Run overlapping charts separately when preserving every chart occurrence matters, because a task deduplicates saved records by app ID or source URL.
• Treat description, rating, review count, price, artwork, and other optional fields as nullable and omit empty values in downstream displays.

Related APIs