# App Rank List API ## API Information - **API Name**: Get Top Apps Rank List - **Request Method**: POST - **API URL**: `/open-api/v1/data` - **API Path**: `/v3/api/open/rank/app/list` - **API Description**: Get app rank list information based on filter conditions, supports pagination - **Pricing**: Retrieving one data result consumes 1 credit **Request Headers:** - Content-Type: application/json - Accept: application/json ## Request Parameters ### Request Structure | Parameter Name | Type | Description | Example | Required | Default | | -------------- | ------ | --------------------------------- | ---------------------------- | -------- | ------- | | key | string | User's external API request key | "your_api_key_here" | Yes | | | uri | string | Interface path | "/v3/api/open/rank/app/list" | Yes | | | params | object | Interface input parameters object | See parameter list below | Yes | | ### Parameter List (params object) | Parameter Name | Type | Description | Example | Required | Default | | ---------------- |---------|-------------------------------------------------------------------------------------------|-----------------| -------- | ------- | | current_page | integer | Current page number | 1 | Yes | | | page_size | integer | Page size | 20 | Yes | | | sort_key | string | Sort field: digg_count_growth- Like , digg_growth_rate- Growth Rate , video_count- Number of ads ，app_download_count- Installs ，latest_download_count- Monthly Installs ，last_month_revenue- Monthly Revenue(USD) | "count_growth" | Yes | | | sort_type | string | Sort type: desc-descending, asc-ascending | "desc" | Yes | | | time | integer | Time range: 0-default | 0 | Yes | | | type | integer | Time type: 0-default, 1-Daily Ranking, 2-Weekly Ranking, 3-Monthly Ranking | 1 | Yes | | | app_category | string | App category, multiple separated by commas | "id6003,id6023" | No | | | app_system | string | App system: ios/android | "ios" | No | | | app_type | string | App type: app/game | "app" | No | | | count_growth_max | double | Data growth maximum value (play count growth) | 1000000 | No | | | count_growth_min | double | Data growth minimum value (play count growth) | 1000 | No | | | growth_rate_max | double | Data growth rate maximum value | 1.0 | No | | | growth_rate_min | double | Data growth rate minimum value | 0.1 | No | | | plat_type | integer | Platform type: 0-all platforms, 1-TikTok, 2-Facebook | 1 | No | | | region | string | Target regions, multiple separated by commas | "US,CA,GB" | No | | | video_count_max | long | Number of ads， Data growth maximum value (play count growth) | 1000000 | No | | | video_count_min | long | Number of ads，Data growth minimum value (play count growth) | 1000 | No | | | app_download_count_max | long | Installs | 1000000 | No | | | app_download_count_min | long | Installs | 1000 | No | | | latest_download_count_max | long | Monthly Installs | 1000000 | No | | | latest_download_count_min | long | Monthly Installs | 1000 | No | | | last_month_revenue_max | long | Monthly Revenue(USD) | 1000000 | No | | | last_month_revenue_min | long | Monthly Revenue(USD) | 1000 | No | | ### Request Example ```bash curl -X POST "https://www.pipispy.com/open-api/v1/data" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "key": "your_api_key_here", "uri": "/v3/api/open/rank/app/list", "params": { "current_page": 1, "page_size": 20, "sort_key": "count_growth", "sort_type": "desc", "time": 1, "type": 1, "app_category": "id6003,id6023", "app_system": "ios", "app_type": "app", "count_growth_min": 1000, "count_growth_max": 1000000, "growth_rate_min": 0.1, "growth_rate_max": 1.0, "plat_type": 1, "region": "US,CA,GB" } }' ``` ## Response Parameters ### Response Body Structure ```json { "code": 200, "message": "success", "data": { "data": [ // App rank list items ], "page": { // Pagination information } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` ### Response Field Description ##### Main Response Fields | Field Name | Type | Description | | ------------- | ------------ | -------------------- | | **code** | integer | Response status code | | **message** | string | Response message | | **data** | object | Response data object | | **version** | string | API version number | | **timestamp** | integer/null | Timestamp | | **sign** | string/null | Signature | | **remaining_credits** | number | Current remaining available credits after this request | | **consumed_credits** | number | Credits consumed by this request | | **success** | boolean | Whether successful | | **fail** | boolean | Whether failed | ##### Data Object Fields | Field Name | Type | Description | | ---------- | ------------- | ---------------------- | | **data** | array[object] | App rank list | | **page** | object | Pagination information | ##### Data Item Fields | Field Name | Type | Description | | ---------------------- | ------------- | -------------------------------------------- | | id | string | App unique identifier ID | | app_name | string | App name | | icon | string | App icon URL | | platform | array[string] | Platform list, e.g. ["tiktok", "facebook"] | | region | array[string] | Target regions list, e.g. ["US", "CA", "GB"] | | app_category | object | App category information | | app_rate | object | App rating information | | app_type | string | App type (app/game) | | app_store | string | App store (apple/google) | | app_download_count | long | Download count | | app_comment_count | long | Comment count | | play_count | long | Play count | | video_count | long | Video count | | digg_count | long | Like count | | put_day | integer | Days since launch | | found_time | long | Discovery timestamp | | latest_found_time | long | Latest discovery timestamp | | is_collection | boolean | Whether already collected | | last_month_revenue | object | Last month revenue information | | play_count_growth_rate | double | Play count growth rate | | digg_growth_rate | double | Like growth rate | | latest_download_count | long | Latest download count | | app_dev_info | object | Developer information | | created_time | long | Creation timestamp | ##### App Category Object Fields | Field Name | Type | Description | | ---------- | ------------- | ----------------- | | id | string | Category ID | | name | string | Category name | | type | string | Category type | | app_system | string | App system | | children | array[object] | Sub-category list | ##### App Rating Object Fields | Field Name | Type | Description | | ---------- | ------ | ------------ | | score | double | Rating score | | count | long | Rating count | ##### Revenue Object Fields | Field Name | Type | Description | | ---------- | ------ | --------------------- | | unit | string | Unit (cent) | | currency | string | Currency type (USD) | | type | string | Type (currency) | | value | long | Revenue value (cents) | ##### Developer Info Object Fields | Field Name | Type | Description | | ----------- | ------ | ----------------------- | | name | string | Developer name | | icon | string | Developer icon | | id | string | Developer ID | | email | string | Developer email | | url | string | Developer link | | website_url | string | Website link (optional) | | avatar | string | Avatar (optional) | ##### Page Object Fields | Field Name | Type | Description | | ------------ | ------- | --------------------- | | total_count | number | Total count | | page_count | number | Total page count | | current_page | number | Current page number | | page_size | number | Page size | | is_next | boolean | Whether has next page | ### Response Example ```json { "code": 200, "message": "success", "data": { "data": [ { "platform": ["tiktok", "facebook"], "id": "17cdd4b2fc9c3e0fc0df", "icon": "https://cdn-app.pipispy.com/15b5139d7abb7892a0624fe0d96b3286.jpg", "region": [ "US", "AU", "CA", "EG", "GB", "BR", "PE", "MX", "FR", "SA", "MY", "JP", "VN", "SG", "IT", "DE", "AE", "PT", "IE", "NL", "PH", "ID", "IN", "ES", "TW", "TR" ], "app_name": "TikTok - Videos, Shop & LIVE", "app_category": { "id": "id36", "name": "App", "type": "app", "app_system": "ios", "children": [ { "id": "id6016", "name": "Entertainment", "type": "app", "app_system": "ios" }, { "id": "id6008", "name": "Photo & Video", "type": "app", "app_system": "ios" } ] }, "app_rate": { "score": 4.7, "count": 18153387 }, "app_type": "app", "app_store": "apple", "app_download_count": 99000000, "app_comment_count": 18153387, "play_count": 49774290, "video_count": 67, "digg_count": 4084565, "put_day": 2627, "found_time": 1616402946, "latest_found_time": 1751806943, "is_collection": false, "last_month_revenue": { "unit": "cent", "currency": "USD", "type": "currency", "value": 15300000000 }, "play_count_growth_rate": 0.0474, "digg_growth_rate": 0.7988, "latest_download_count": 6000000, "app_dev_info": { "website_url": "http://www.tiktok.com", "name": "TikTok Ltd.", "icon": "https://cdn-app.pipispy.com/15b5139d7abb7892a0624fe0d96b3286.jpg", "id": "1322881000", "email": "", "url": "https://apps.apple.com/us/developer/tiktok-ltd/id1322881000" }, "created_time": 1396411200 } ], "page": { "total_count": 5441, "page_count": 273, "current_page": 1, "page_size": 20, "is_next": true } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` ## Error Code Description | Error Code | Description | | ---------- | -------------------------------- | | 200 | Success | | 400 | Bad Request - Invalid parameters | | 401 | Unauthorized - Invalid API key | | 500 | Internal Server Error |