Appfigures APIapp.appfigures.com ↗
Get ranked iOS App Store apps with ratings, pricing, revenue estimates, and demographics. Covers 28 categories, multiple countries, and device types.
What is the Appfigures API?
The Appfigures API exposes three endpoints for querying iOS App Store top-app rankings, with get_top_apps returning up to 500 ranked apps per request across 28 categories, multiple countries, and device types. Each app entry includes rank, developer, price, and currency. A separate get_app_details call returns deeper metadata including ratings, active status, supported devices, version, and country availability for any specific app ID.
curl -X GET 'https://api.parse.bot/scraper/c27a2990-1e5e-405c-938e-8e06c46d27ff/get_top_apps?limit=10&store=ios-app-store&device=iphone&country=united-states&category=books&list_type=topgrossing' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace app-appfigures-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Appfigures Top Apps API — browse categories, fetch rankings, drill into app details."""
from parse_apis.appfigures_top_apps_api import (
Appfigures, ListType, Device, CategorySlug, AppNotFound,
)
client = Appfigures()
# List all available categories to discover what's available.
for cat in client.categories.list(limit=5):
print(cat.slug, cat.category_id)
# Construct a category and fetch its top grossing apps.
games = client.category(CategorySlug.GAMES)
for app in games.top_apps.list(list_type=ListType.TOP_GROSSING, device=Device.IPHONE, limit=3):
print(app.rank, app.name, app.developer, app.price, app.currency)
# Drill into the first result for full details (monetization, demographics, estimates).
top_app = games.top_apps.list(list_type=ListType.FREE, limit=1).first()
if top_app:
detail = top_app.details()
print(detail.name, detail.rating.stars, detail.rating.count)
print(detail.monetization.is_free, detail.monetization.has_iaps, detail.monetization.has_subs)
if detail.estimates.downloads.value:
print(detail.estimates.downloads.value, detail.estimates.revenue.value)
# Typed error handling: catch AppNotFound for an invalid product ID.
try:
bad = client.category(CategorySlug.TOP_OVERALL).top_apps.list(limit=1).first()
if bad:
bad_detail = bad.details()
print(bad_detail.name)
except AppNotFound as exc:
print(f"App not found: {exc.product_id}")
print("exercised: categories.list / category().top_apps.list / app.details / AppNotFound")
Retrieve the top-ranked apps for a given iOS App Store category. Returns up to 200 apps for grossing lists and up to 500 for free/paid lists. Each result includes rank position, app identity, developer, and price. The response includes metadata about the category and ranking timestamp. Paginate client-side by adjusting limit; server returns a single snapshot per request.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of apps to return (up to 200 for grossing, 500 for free/paid). |
| store | string | App store identifier. |
| device | string | Device type. |
| country | string | Country slug for the storefront (e.g. 'united-states', 'united-kingdom', 'japan', 'germany'). |
| category | string | Category slug for the ranking list. |
| list_type | string | Type of ranking list. |
{
"type": "object",
"fields": {
"apps": "array of ranked app objects with rank, id, name, developer, developer_id, storefront, vendor_identifier, price, currency",
"category": "string - Category display name",
"list_type": "string - List type code (free/paid/topgrossing)",
"timestamp": "string - When the ranking was last updated (ISO 8601)",
"category_id": "integer - Internal category ID",
"total_count": "integer - Total apps available in this list",
"apps_returned": "integer - Number of apps in response"
}
}About the Appfigures API
Endpoints and What They Return
The API has three endpoints. get_top_apps returns a ranked list of iOS apps for a given category, country, list type, and device. The list_type parameter accepts free, paid, or topgrossing, and the category parameter accepts slugs returned by get_categories. Results include each app's rank, name, developer, developer_id, price, currency, storefront, and vendor_identifier, plus response-level metadata: category, list_type, timestamp, category_id, total_count, and apps_returned. Grossing lists cap at 200 results; free and paid lists support up to 500.
App Detail Fields
get_app_details accepts a product_id from get_top_apps results and returns comprehensive app metadata: icon URL, name, price object with currency and amount, store, active status, rating with stars and count, devices array, version, and countries array. This is the endpoint to use when you need ratings data, version history, or multi-country availability for a specific app.
Category Discovery
get_categories returns a static list of all 28 available iOS App Store categories. Each entry includes a slug for use in get_top_apps and an internal category_id. No parameters are required. Use this endpoint first to enumerate valid category inputs before querying top-app lists.
Coverage Notes
Country coverage is controlled by the country parameter, which accepts slugs like united-states, united-kingdom, japan, and germany. The device parameter allows filtering by device type (e.g., iPhone vs. iPad). Rankings reflect the timestamp field in each response, which indicates when the list was last refreshed.
The Appfigures API is a managed, monitored endpoint for app.appfigures.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when app.appfigures.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official app.appfigures.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track weekly rank movement for apps in a specific iOS category and country by polling
get_top_appswith a fixedcategoryandlist_type. - Compare app store ratings across the top-grossing list in multiple countries by looping
get_top_appswith differentcountryvalues and enriching withget_app_details. - Identify free vs. paid vs. grossing leaders in a single category by running three
get_top_appsrequests with eachlist_typeoption. - Build a competitor-monitoring dashboard by pulling
developer_idfrom ranked results and then fetching full app details for each competitor's titles. - Audit which app versions are dominant in a category by collecting
versionfields fromget_app_detailsacross top-ranked app IDs. - Enumerate all valid iOS categories and their IDs with
get_categoriesto dynamically build a category picker UI without hardcoding slugs. - Filter available countries for a specific app by reading the
countriesarray returned byget_app_details.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Appfigures have an official developer API?+
What does `get_app_details` return beyond what `get_top_apps` includes?+
get_top_apps returns summary fields: rank, name, developer, developer_id, price, currency, storefront, and vendor_identifier. get_app_details adds the app icon URL, full rating object (stars float and review count), supported devices array, current version string, active boolean, and an array of country codes where the app is available. Revenue estimates and demographic data shown on the Appfigures site are not currently returned by either endpoint.Does the API cover Android or Google Play rankings?+
store field in responses returns apple and get_categories returns categories for ios-app-store only. You can fork this API on Parse and revise it to add a Google Play endpoint targeting Android rankings.How fresh are the rankings returned by `get_top_apps`?+
timestamp field (ISO 8601) indicating when that ranking list was last updated. Appfigures typically refreshes top-app lists daily, but the exact cadence can vary by country and category. Your application should read the timestamp field rather than assuming a fixed update interval.Can I retrieve historical ranking data or trend charts for a specific app?+
get_top_apps and current app metadata via get_app_details. There is no endpoint for rank history over time. You can fork this API on Parse and revise it to add a historical rankings endpoint if Appfigures exposes that data in the surface you need.