The /aso resource provides access to keyword rank trends and stats for keywords and apps tracked in your Appfigures account.
Getting Keyword Stats for an App
Request
GET /aso/stats?{filters}
Arguments
| Field
| Type
| Description |
| products |
Product ID |
The Appfigures ID of the app to get data for. At this time only one app can be set per request. |
| countries |
String |
the ISO code of the country to fetch results in. At this time only one country can be set per request. |
| device |
Enum |
The device to fetch data from. Only applicable for iOS apps. options: `handheld` and `tablet`. |
| start |
Date |
The date and time of the beginning of the date range to fetch. |
| end |
Date |
The date and time of the end of the date range to fetch. |
| granularity |
Enum |
`daily` or `hourly`. Some plans do not have access to hourly granularity. |
Response
| Field
| Type
| Description |
| avg_position |
Number |
The average of all ranks using the latest rank positions and not including unranked keywords. |
| avg_position_delta |
Number |
The average of all rank changes using the latest rank change and not including unranked keywords. |
| highest |
Number |
The highest position the app was seen in for any of the tracked keywords. The best value is 1. |
| highest_delta |
Number |
The biggest increase (improvement) in rank using the latest position and latest change. |
| lowest |
Number |
The lowest position the app was seen in for any of the tracked keywords. |
| lowest_delta |
Number |
The biggest decrease (decline) in rank using the latest position and latest change. |
| top_5 |
Number |
The number of keywords, from your tracked list, that have a rank greater than or equal to 5 right now. |
| top_25 |
Number |
The number of keywords, from your tracked list, that have a rank greater than or equal to 25 right now. |
| top_100 |
Number |
The number of keywords, from your tracked list, that have a rank greater than or equal to 100 right now. |
| ranked_keywords |
Number |
The number of keywords, from your tracked list, that the selected app is ranked in. |
| total_keywords |
Number |
The number of keywords in your tracked list. |
| positive |
Number |
The number of keywords, from your tracked list, where the app’s rank moved up (improved) during the selected date range. |
| negative |
Number |
The number of keywords, from your tracked list, where the app’s rank moved down (declined) during the selected date range. |
| unranked_keywords |
Number |
The number of keywords, from your tracked list, that the selected app is not ranked in. |
| unchanged |
Number |
The number of keywords, from your tracked list, that have not had any rank changes in the selected date range. |
Example Response
// GET /aso/stats?
products=333918141896&
countries=US&
granularity=hourly&
start=2021-02-03T00:00:00&
end=2021-02-09T17:00:00&
device=handheld
{
"avg_position": 21,
"avg_position_delta": 9,
"highest": 1,
"highest_delta": 0,
"lowest": 43,
"lowest_delta": 15,
"top_5": 1,
"top_25": 2,
"top_100": 2,
"ranked_keywords": 5,
"total_keywords": 5,
"positive": 4,
"negative": 0,
"unranked_keywords": 0,
"unchanged": 1
}
Getting Rank Trends
Request
GET /aso?{filters}
Arguments
| Field
| Type
| Description |
| group_by |
Enum |
How to group the results. At this time only the `keyword` value is supported. |
| products |
Product ID |
The Appfigures ID of the app to get data for. At this time only one app can be set per request. |
| countries |
String |
the ISO code of the country to fetch results in. At this time only one country can be set per request. |
| device |
Enum |
The device to fetch data from. Only applicable for iOS apps. options: `handheld` and `tablet`. |
| start_date |
Date |
The date and time of the beginning of the date range to fetch. |
| end_date |
Date |
The date and time of the end of the date range to fetch. |
| normalize |
Bool |
Whether the results should include entries for days without data or not. |
| granularity |
Enum |
`daily` or `hourly`. Some plans do not have access to hourly granularity. |
| page |
Number |
The page you’d like to fetch. |
Response
The response is paged, which means it’ll return two main sections: metadata and results
Metadata.Resultset:
| Field
| Type
| Description |
| count |
Number |
The max number of results per page. |
| page |
Number |
The current page of results being returned. |
| total_count |
Number |
The number of results for this request. |
| total_pages |
Number |
The number of pages for this request. |
Results:
| Field
| Type
| Description |
| position |
Number |
The rank for the selected app for this search. |
| delta |
Number |
The change in rank, represented by the number of positions moved up or down, between the latest scan and the one before it, using hourly granularity. |
| last_change |
Date |
The date of the last change in rank. |
| num_apps |
Number |
The total number of apps that rank for this keyword. |
| keyword_id |
String |
The keyword’s Appfigures ID. |
| keyword_term |
String |
The search term. This field may include emoji. |
| popularity |
Number |
The popularity score for this keyword, on a scale of 1 – 100. This metric may not be available to all plans. |
| competitiveness |
Number |
The competitiveness score for this keyword, on a scale of 1 – 100. This metric may not be available to all plans. |
Example Response
// GET /aso?
group_by=keyword&
products=333918141896&
countries=US&
device=handheld&
start_date=2021-02-03T00:00:00&
end_date=2021-02-09T17:00:00&
normalize=true&
granularity=hourly&
time_zone=utc&
page=1
{
"metadata": {
"resultset": {
"count": 500,
"page": 1,
"total_count": 5,
"total_pages": 1
}
},
"results": [
{
"position": 12,
"delta": 1,
"last_change": "2021-02-09T16:00:00",
"num_apps": 269,
"keyword_id": "1d86c5c8b1cdcae0ad30574e31e6288a",
"keyword_term": "stream tv",
"popularity": 32,
"competitiveness": 92,
"importance": "6.12"
},
{
"position": 29,
"delta": 8,
"last_change": "2021-02-07T22:00:00",
"num_apps": 231,
"keyword_id": "456f3e168ea7f915cd5898bce0162ab4",
"keyword_term": "stream shows",
"popularity": 5,
"competitiveness": 94,
"importance": "0.74"
},
{
"position": 1,
"delta": 0,
"num_apps": 252,
"keyword_id": "54818b05d116eadc7f67517a3a6e4b33",
"keyword_term": "discovery",
"popularity": 52,
"competitiveness": 100,
"importance": "52.00"
},
{
"position": 23,
"delta": -1,
"last_change": "2021-02-09T09:00:00",
"num_apps": 241,
"keyword_id": "7d520907f526f36930df8491326b1dbc",
"keyword_term": "tv shows",
"popularity": 39,
"competitiveness": 100,
"importance": "6.16"
},
{
"position": 43,
"delta": -1,
"last_change": "2021-02-09T16:00:00",
"num_apps": 273,
"keyword_id": "f7b44cfafd5c52223d5498196c8a2e7b",
"keyword_term": "stream",
"popularity": 57,
"competitiveness": 98,
"importance": "7.70"
}
]
}
