Keyword Ranks

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"
    }
  ]
}