Apple Search Ad Intelligence

The /search-ads resource provides programmatic access to Apple Search Ads Intelligence data by app and also by keyword.

Getting Paid Keywords for an App

Using this route, you can identify the keywords any product, app or game, appeared in paid search results for within a custom date range.

Request

GET /search-ads/products?{filters}

Arguments

Field	Type	Description
product	Product ID	The Appfigures ID of the app to get data for. At this time only one app can be set per request.
countries	List	One or more ISO-2 codes of the countries to fetch results for.
start	Date	The date and time of the beginning of the date range to fetch. Format: yyyy-mm-dd or as a negative number (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 page sizes may take longer per request.

Response

The list of keywords can be very long and as such the results are paged. The response is wrapped in an object that contains relevant information for the number of results (metadata key) in addition to the actual results (results key).

Metadata

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

Results

Field	Type	Description
countries	Object	The ISO2 code for the country as well as the share of impressions, of all keywords the app has been observed in, within the country.
keyword_id	String	The Appfigures ID of the keyword.
keyword_term	String	The keyword this app was observed in.
product_id	String	The Appfigures ID of the app.
product_name	String	The name of the app in the store.
impressions_share	String	How many times we’ve observed the app appear for this search term divided by the total number of times we’ve observed the app appear in paid search results.

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

Using this route, you can identify products, both apps and games, that have appeared in paid search results for any 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. At this time only one app can be set per request.
country	List	The ISO-2 code of the country to fetch results for. Only one country can be requested at a time.
term	String	The keyword (not ID) to get results for.
storefront	String	The Appfigures ID of the store to get results from. The only supported store front right now is apple:ios.
page	Number	The page for the request. Defaults to 1.
count	Number	The number of apps to receive in the response. Defaults to 500.

Response

The list of products can be very long and as such the results are paged. The response is wrapped in an object that contains relevant information for the number of results (metadata key) in addition to the actual results (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 available for this set of parameters.
total_pages	Number	The total number of pages for this set of parameters.

Results

Field	Type	Description
countries	Object	The ISO2 code of the country along with the number of times we’ve observed the product in search results in the country.
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 product in the store.
impressions	Number	The number of time we’ve observed the product 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"
  },
  ...
}