# Appfigures — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Track top-performing iOS apps across categories with detailed insights on rankings, monetization models, ratings, revenue estimates, and user demographics. Monitor app performance metrics and discover trending applications by category to stay informed about the competitive app market landscape.

**Category:** Developer Tools | **Website:** [app.appfigures.com/top-apps/ios-app-store/united-states/iphone/top-overall](https://app.appfigures.com/top-apps/ios-app-store/united-states/iphone/top-overall) | **Docs:** [parse.bot/marketplace/f47338f8-3097-4cda-a68d-6a3b564ac506/app-appfigures-com-api](https://parse.bot/marketplace/f47338f8-3097-4cda-a68d-6a3b564ac506/app-appfigures-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-app-appfigures-com-api-f47338f8/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_app_details

Retrieve comprehensive details for a specific app by its Appfigures product ID (obtained from get_top_apps results). Returns full app metadata including description, monetization model, ratings, monthly download and revenue estimates, user demographics, supported countries and languages, categories, screenshots, and version history. One round-trip per app; batch lookups are not supported.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Appfigures product ID (the 'id' field from get_top_apps results). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-app-appfigures-com-api-f47338f8/get_app_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>"}'
```

### get_categories

List all available iOS App Store categories with their URL slugs and internal IDs. Returns the complete category vocabulary; use slug values as the 'category' parameter in get_top_apps. The list is static and does not paginate.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-app-appfigures-com-api-f47338f8/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_top_apps

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.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category slug for the ranking list. |
| `country` | string | No | Country slug for the storefront (e.g. 'united-states', 'united-kingdom', 'japan', 'germany'). |
| `device` | string | No | Device type. |
| `limit` | integer | No | Maximum number of apps to return (up to 200 for grossing, 500 for free/paid). |
| `list_type` | string | No | Type of ranking list. |
| `store` | string | No | App store identifier. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-app-appfigures-com-api-f47338f8/get_top_apps \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","country":"<string>","device":"<string>","limit":"<integer>","list_type":"<string>","store":"<string>"}'
```