Apple Search Ads Intelligence

The /search-ads routes show you which keywords an app appears for in Apple Search Ads, and which apps appear in paid results for a keyword.

The data comes from the paid search results we observe. Impressions and impression shares are our estimates, not Apple’s figures.

Getting Paid Keywords for an App

This route returns the keywords an app or game appeared for in paid search results over a date range you set.

Request

GET /search-ads/products?{filters}

Arguments

Field	Type	Description
product	Product ID	The Appfigures ID of the app to get data for. You can set only one app per request.
countries	List	One or more ISO-2 codes of the countries to get results for.
start	Date	The start of the date range. Format: yyyy-mm-dd, or a negative number of days (ex. -30 = 30 days ago).
page	Number	A page number starting with 1. Defaults to 1.
count	Number	The number of keywords per page. Defaults to 10. Larger pages can make requests slower.

Response

The list of keywords can be long, so results are paged. The response wraps paging details (metadata key) and the results themselves (results key).

Metadata

Field	Type	Description
count	Number	The number of keywords per page.
page	Number	The current page of results.
total_count	Number	The total number of keywords for this set of parameters.
total_pages	Number	The total number of pages for this set of parameters.

Results

Field	Type	Description
countries	Object	Each country’s ISO-2 code, with the app’s estimated share of impressions there out of all keywords we’ve observed the app in.
keyword_id	String	The Appfigures ID of the keyword.
keyword_term	String	The keyword we observed the app in.
product_id	String	The Appfigures ID of the app.
product_name	String	The name of the app in the store.
impressions_share	String	Our estimate of the app’s share of paid impressions: the number of times we observed the app for this keyword, divided by the number of times we observed it in paid search results overall.

Example Response

// GET /search-ads/products?
         start_date=-30
         &product=334288907959
         &countries=US,GB
         &count=10

{
  "metadata": {
    "resultset": {
      "count": 10,
      "page": 1,
      "total_count": 2339,
      "total_pages": 234
    }
  },
  "results": [{
    "countries": [{
      "country": "GB",
      "impressions_share": "5.29"
    }, {
      "country": "US",
      "impressions_share": "6.32"
    }],
    "keyword_id": "689e68c4024c2e61e1e02ff6d0182a54",
    "keyword_term": "nba games for free",
    "product_id": 334288907959,
    "product_name": "Bubble Shooter Pop!",
    "impressions_share": "5.79"
  }]
}

Listing Apps that Pay for a Keyword

This route returns the apps and games that appeared in paid search results for a keyword in the last 14 days.

Request

GET /search-ads?{filters}

Arguments

Field	Type	Description
product	Product ID	The Appfigures ID of the app to get data for. You can set only one app per request.
country	List	The ISO-2 code of the country to get results for. You can request only one country at a time.
term	String	The keyword (not its ID) to get results for.
storefront	String	The Appfigures ID of the store to get results from. The only supported storefront is apple:ios.
page	Number	The page to get. Defaults to 1.
count	Number	The number of apps per page. Defaults to 500.

Response

The list of apps can be long, so results are paged. The response wraps paging details (metadata key) and the results themselves (results key).

Metadata

Field	Type	Description
count	Number	The number of apps per page.
page	Number	The current page of results.
total_count	Number	The total number of apps for this set of parameters.
total_pages	Number	The total number of pages for this set of parameters.

Results

Field	Type	Description
countries	Object	Each country’s ISO-2 code, with the number of times we observed the app in paid search results there.
keyword_id	String	The Appfigures ID of the keyword.
keyword_term	String	The keyword in plain text.
product_id	Number	The Appfigures ID of the app.
product_name	String	The name of the app in the store.
impressions	Number	The number of times we observed the app in paid search results for the keyword.

Example Response

// GET /search-ads?
         &term=games
         &country=US

{
  "metadata": {
    "resultset": {
      "count": 10,
      "page": 1,
      "total_count": 30,
      "total_pages": 3
    }
  },
  "results": [{
    "impressions": 24,
    "countries": [{
      "country": "US",
      "impressions": 24
    }],
    "keyword_id": "9cfa7aefcc61936b70aaec6729329eda",
    "keyword_term": "games",
    "product_id": 333741399334,
    "product_name": "SudoBlox: Sudoku Block Puzzle"
  },
  ...
  ]
}