Keyword Ranks (App Store Optimization)

The /aso resource gives you keyword rank trends and stats for the keywords and apps you track in Appfigures.

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. You can set only one app per request.
countries	String	The ISO code of the country to fetch results in. You can set only one country per request.
device	Enum	The device to fetch data from. Applies only to 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. Hourly granularity isn’t available on all plans.

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, where the app ranks in the top 5 right now.
top_25	Number	The number of keywords, from your tracked list, where the app ranks in the top 25 right now.
top_100	Number	The number of keywords, from your tracked list, where the app ranks in the top 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 isn’t ranked in.
unchanged	Number	The number of keywords, from your tracked list, that haven’t 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. You can set only one app per request.
countries	String	The ISO code of the country to fetch results in. You can set only one country per request.
device	Enum	The device to fetch data from. Applies only to 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 to include entries for days without data.
granularity	Enum	daily or hourly. Hourly granularity isn’t available on all plans.
page	Number	The page you’d like to fetch.

Response

The response is paged. It has 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 to 100. Not available on all plans.
competitiveness	Number	The competitiveness score for this keyword, on a scale of 1 to 100. Not available on 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"
    }
  ]
}