app_data/apple/app_list/task_get/advanced

Get Apple App List Results by id

This endpoint will provide you with a list of applications published in the top app charts on the App Store platform, including app IDs, ratings, prices, titles, and more. The results are specific to the app_collection as well as the location and language parameters specified in the POST request.

GET

Your account will be charged only for setting a task. You can get the results of the task within the next 30 days for free.
The cost can be calculated on the Pricing page.

Description of the fields for sending a request:

Field name	Type	Description
`id`	string	task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time

‌‌‌‌
‌‌As a response of the API server, you will receive JSON-encoded data containing a tasks array with the information specific to the set tasks.

You can also get all available SERP features by making a request to the following Sandbox URL:
https://sandbox.dataforseo.com/v3/app_data/apple/app_list/task_get/advanced/00000000-0000-0000-0000-000000000000
The response will include all available items in the Apple App List Advanced endpoint with the fields containing dummy data.
You won’t be charged for using Sandbox endpoints.

Description of the fields in the results array:

Field name	Type	Description
`version`	string	the current version of the API
`status_code`	integer	general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions
`status_message`	string	general informational message you can find the full list of general informational messages here
`time`	string	execution time, seconds
`cost`	float	total tasks* cost, USD*
`tasks_count`	integer	the number of tasks in the `tasks`* array*
`tasks_error`	integer	the number of tasks in the `tasks`* array that were returned an error*
`tasks`	array	array of tasks
`id`	string	task identifier unique task identifier in our system in the UUID format
`status_code`	integer	status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here
`status_message`	string	informational message of the task you can find the full list of general informational messages here
`time`	string	execution time, seconds
`cost`	float	cost of the task, USD
`result_count`	integer	number of elements in the `result` array
`path`	array	URL path
`data`	object	contains the same parameters that you specified in the POST request
`result`	array	array of results
`keyword`	string	app collection received in a POST array
`se_domain`	string	search engine domain in a POST array
`location_code`	integer	location code in a POST array
`language_code`	string	language code in a POST array
`check_url`	string	direct URL to search engine results in this case, the value will be `null`
`datetime`	string	date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`
`se_results_count`	integer	the total number of results
`items_count`	integer	the number of app items in the results array you can get more results by using the `depth` parameter when setting a task
`items`	array	found apps you can get more results by using the `depth` parameter when setting a task
`type`	string	the result’s type possible result types: `"app_store_search_organic"`
`rank_group`	integer	position within a group of elements with identical `type` values positions of elements with different `type` values are omitted from `rank_group`
`rank_absolute`	integer	absolute rank among all the listed apps absolute position among all apps on the list
`position`	string	the alignment of the app in SERP can take the following values: `left`
`app_id`	string	ID of the app
`title`	string	title of the app
`url`	string	URL to the app page on the App Store
`icon`	string	URL to the app icon
`reviews_count`	integer	the total number of reviews of the app
`rating`	object	average rating of the app
`rating_type`	string	the type of the rating can take the following values: `Max5`
`value`	float	the value of the rating
`votes_count`	integer	the amount of feedback in this case, the value will be `null`
`rating_max`	integer	the maximum value for a `rating_type` the maximum value for `Max5` is 5
`is_free`	boolean	indicates whether the app is free
`price`	object	price of the app
`current`	float	current price refers to the current price indicated in the element
`regular`	float	regular price refers to the regular price indicated in the element
`max_value`	float	the maximum price refers to the maximum price indicated in the element
`currency`	string	currency of the listed price ISO code of the currency applied to the price
`is_price_range`	boolean	price is provided as a range indicates whether a price is provided in a range
`displayed_price`	string	price string in the result raw price string as provided in the result

‌‌

Instead of ‘login’ and ‘password’ use your credentials from https://app.dataforseo.com/api-access

# Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access 
login="login" 
password="password" 
cred="$(printf ${login}:${password} | base64)" 
id="04011058-0696-0199-0000-2196151a15cb" 
curl --location --request GET "https://api.dataforseo.com/v3/app_data/apple/app_list/task_get/advanced/${id}" 
--header "Authorization: Basic ${cred}"  
--header "Content-Type: application/json"

<?php
// You can download this file from here https://cdn.dataforseo.com/v3/examples/php/php_RestClient.zip
require('RestClient.php');
$api_url = 'https://api.dataforseo.com/';
// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
$client = new RestClient($api_url, null, 'login', 'password');

try {
	$result = array();
	// #1 - using this method you can get a list of completed tasks
	// GET /v3/app_data/apple/app_list/tasks_ready
	$tasks_ready = $client->get('/v3/app_data/apple/app_list/tasks_ready');
	// you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
	if (isset($tasks_ready['status_code']) AND $tasks_ready['status_code'] === 20000) {
		foreach ($tasks_ready['tasks'] as $task) {
			if (isset($task['result'])) {
				foreach ($task['result'] as $task_ready) {
					// #2 - using this method you can get results of each completed task
					// GET /v3/app_data/apple/app_list/task_get/advanced/$id
					if (isset($task_ready['endpoint_advanced'])) {
						$result[] = $client->get($task_ready['endpoint_advanced']);
					}
					// #3 - another way to get the task results by id
					// GET /v3/app_data/apple/app_list/task_get/advanced/$id
					/*
					if (isset($task_ready['id'])) {
						$result[] = $client->get('/v3/app_data/apple/app_list/task_get/advanced/' . $task_ready['id']);
					}
					*/
				}
			}
		}
	}
	print_r($result);
	// do something with result
} catch (RestClientException $e) {
	echo "n";
	print "HTTP code: {$e->getHttpCode()}n";
	print "Error code: {$e->getCode()}n";
	print "Message: {$e->getMessage()}n";
	print  $e->getTraceAsString();
	echo "n";
}
$client = null;
?>

const task_id = '02231934-2604-0066-2000-570459f04879';

const axios = require('axios');

axios({
    method: 'get',
    url: 'https://api.dataforseo.com/v3/app_data/apple/app_list/task_get/advanced' + task_id,
    auth: {
        username: 'login',
        password: 'password'
    },
    headers: {
        'content-type': 'application/json'
    }
}).then(function (response) {
    var result = response['data']['tasks'];
    // Result data
    console.log(result);
}).catch(function (error) {
    console.log(error);
});

from client import from client import RestClient
# You can download this file from here https://cdn.dataforseo.com/v3/examples/python/python_Client.zip
client = RestClient("login", "password")
# get the task results by id
# GET /v3/app_data/apple/app_list/task_get/advanced/$id
id = "06141103-2692-0309-1000-980b778b6d25"
response = client.get("/v3/app_data/apple/app_list/task_get/advanced/" + id)
# you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if response["status_code"] == 20000:
    print(response)
    # do something with result
else:
    print("error. Code: %d Message: %s" % (response["status_code"], response["status_message"]))

using Newtonsoft.Json;
using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task app_data_apple_app_list_task_get_by_id()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                // Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            // get the task results by id
            // GET /v3/app_data/apple/app_list/task_get/advanced/$id
            // use the task identifier that you recieved upon setting a task
            string id = "06141103-2692-0309-1000-980b778b6d25";
            var taskGetResponse = await httpClient.GetAsync("/v3/app_data/apple/app_list/task_get/advanced/" + id);
            var result = JsonConvert.DeserializeObject<dynamic>(await taskGetResponse.Content.ReadAsStringAsync());
            if (result.tasks != null)
            {
                var fst = result.tasks.First;
                // you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
                if (fst.status_code >= 40000 || fst.result == null)
                    Console.WriteLine($"error. Code: {fst.status_code} Message: {fst.status_message}");
                else
                    // do something with result
                    Console.WriteLine(String.Join(Environment.NewLine, fst));
            }
            else
                Console.WriteLine($"error. Code: {result.status_code} Message: {result.status_message}");
        }
    }
}

The above command returns JSON structured like this:

{
    "version": "0.1.20220422",
    "status_code": 20000,
    "status_message": "Ok.",
    "time": "0.0793 sec.",
    "cost": 0,
    "tasks_count": 1,
    "tasks_error": 0,
    "tasks": [
        {
            "id": "04281445-1535-0422-0000-6f3f7b9923c0",
            "status_code": 20000,
            "status_message": "Ok.",
            "time": "0.0255 sec.",
            "cost": 0,
            "result_count": 1,
            "path": [
                "v3",
                "app_data",
                "apple",
                "app_list",
                "task_get",
                "advanced",
                "04281445-1535-0422-0000-6f3f7b9923c0"
            ],
            "data": {
                "se_type": "app_list",
                "se": "apple",
                "api": "app_data",
                "function": "app_list",
                "app_collection": "top_free_ios",
                "location_code": 2840,
                "language_code": "en",
                "depth": 200,
                "app_category": "games",
                "device": "desktop",
                "os": "windows"
            },
            "result": [
                {
                    "keyword": "top_free_ios",
                    "se_domain": "itunes.apple.com",
                    "location_code": 2840,
                    "language_code": "en",
                    "check_url": null,
                    "datetime": "2022-04-28 11:45:54 +00:00",
                    "se_results_count": 100,
                    "items_count": 100,
                    "items": [
                        {
                            "type": "app_store_search_organic",
                            "rank_group": 1,
                            "rank_absolute": 1,
                            "position": "left",
                            "app_id": "1095569891",
                            "title": "Wordle!",
                            "url": "https://apps.apple.com/us/app/wordle/id1095569891",
                            "icon": "https://is3-ssl.mzstatic.com/image/thumb/Purple116/v4/51/f0/6c/51f06c3e-73e1-4c75-f697-4f3161020676/source/512x512bb.jpg",
                            "reviews_count": 339396,
                            "rating": {
                                "rating_type": "Max5",
                                "value": 4.49451,
                                "votes_count": 339396,
                                "rating_max": 5
                            },
                            "is_free": true,
                            "price": {
                                "current": 0,
                                "regular": null,
                                "max_value": null,
                                "currency": "USD",
                                "is_price_range": false,
                                "displayed_price": null
                            }
                        },
                        {
                            "type": "app_store_search_organic",
                            "rank_group": 2,
                            "rank_absolute": 2,
                            "position": "left",
                            "app_id": "1595199218",
                            "title": "Deliver It 3D",
                            "url": "https://apps.apple.com/us/app/deliver-it-3d/id1595199218",
                            "icon": "https://is2-ssl.mzstatic.com/image/thumb/Purple122/v4/bf/6c/9b/bf6c9bf9-e791-e580-743a-61efdd996fe3/source/512x512bb.jpg",
                            "reviews_count": 4987,
                            "rating": {
                                "rating_type": "Max5",
                                "value": 4.66974,
                                "votes_count": 4987,
                                "rating_max": 5
                            },
                            "is_free": true,
                            "price": {
                                "current": 0,
                                "regular": null,
                                "max_value": null,
                                "currency": "USD",
                                "is_price_range": false,
                                "displayed_price": null
                            }
                        },
                        {
                            "type": "app_store_search_organic",
                            "rank_group": 3,
                            "rank_absolute": 3,
                            "position": "left",
                            "app_id": "1599121822",
                            "title": "Tall Man Run",
                            "url": "https://apps.apple.com/us/app/tall-man-run/id1599121822",
                            "icon": "https://is4-ssl.mzstatic.com/image/thumb/Purple112/v4/ad/ca/54/adca54ce-bdfa-ab25-ec13-4dfd683321f2/source/512x512bb.jpg",
                            "reviews_count": 13793,
                            "rating": {
                                "rating_type": "Max5",
                                "value": 4.61828,
                                "votes_count": 13793,
                                "rating_max": 5
                            },
                            "is_free": true,
                            "price": {
                                "current": 0,
                                "regular": null,
                                "max_value": null,
                                "currency": "USD",
                                "is_price_range": false,
                                "displayed_price": null
                            }
                        },
                        {
                            "type": "app_store_search_organic",
                            "rank_group": 4,
                            "rank_absolute": 4,
                            "position": "left",
                            "app_id": "512939461",
                            "title": "Subway Surfers",
                            "url": "https://apps.apple.com/us/app/subway-surfers/id512939461",
                            "icon": "https://is5-ssl.mzstatic.com/image/thumb/Purple122/v4/11/59/fd/1159fdfa-574f-4259-6235-bc31dd1b9d0b/source/512x512bb.jpg",
                            "reviews_count": 1700123,
                            "rating": {
                                "rating_type": "Max5",
                                "value": 4.63005,
                                "votes_count": 1700123,
                                "rating_max": 5
                            },
                            "is_free": true,
                            "price": {
                                "current": 0,
                                "regular": null,
                                "max_value": null,
                                "currency": "USD",
                                "is_price_range": false,
                                "displayed_price": null
                            }
                        }
                    ]
                }
            ]
        }
    ]
}