Keyword Metrics by App

App Keyword Ranking - History

Changed on

<b>Price</b> <table> <thead><tr><th>Metrics</th><th>Comment</th><th>Credits/app/keyword for 1 day</th><th>Credits/app/keyword per extra day</th></tr></thead> <tbody> <tr><td><b>rank</b></td><td>Ranking of an app for a keyword.</td><td>10</td><td>1</td></tr> <tr><td><b>installs</b></td><td>The estimated number of daily installs driven by a keyword to an app.</td><td>10</td><td>1</td></tr> </tbody> </table> <Callout icon="📘" theme="info"><b>Ranked, unranked or no data</b><p>To know whether your app is ranked on a keyword or not, you can refer to the following logic in the response data:</p><p>• <code>value</code> = non-null and <code>fetch_performed</code> = <code>true</code> ➔ ranked<br/>• <code>value</code> = <code>null</code> and <code>fetch_performed</code> = <code>true</code> ➔ unranked<br/>• <code>value</code> = <code>null</code> and <code>fetch_performed</code> = <code>false</code> ➔ no data</p><p>In addition to <code>value</code>, <b>you can use <code>effective_value</code>, that corresponds to a value that is guaranteed to be non-null</b>. The logic to compute <code>effective_value</code> is:</p><p>• If <code>value</code> is not <code>null</code>, <code>effective_value</code> = <code>value</code><br/>• Otherwise, if <code>fetch_performed</code> = <code>true</code>, then <code>effective_value</code> = <code>501</code>, the numeric representation of unranked<br/>• Otherwise, if there is at least one non-null value in the date range, take the closest day to the missing day and use that <code>value</code> (an average if two days are equally close)<br/>• Otherwise, defaults to <code>501</code></p></Callout>

get/apps/keywords-rankings/history.json

Request

  • Base URL
    https://public-api.apptweak.com/api/public/store
  • URL
    https://public-api.apptweak.com/api/public/store/apps/keywords-rankings/history.json
  • Auth
    API key in header x-apptweak-key

Query parameters

appsstring required

Comma-separated list of app IDs (max 5). <a href="https://developers.apptweak.com/reference/how-to-find-app-ids" target="_blank"><b>How to find App IDs?</b></a>

keywordsstring required

Comma separated list of keywords. Max 5 keywords are allowed.

metricsstring required

Comma separated list of metrics (rank, installs).

countrystring

Two-letter country code (us, gb, fr). Accepted values: <a href="https://developers.apptweak.com/reference/countries-1" target="_blank"><code>GET /api/public/apptweak/countries</code></a> with store=ios or store=android. Defaults to us.

languagestring

AppTweak language code, not always ISO: US English is us, US Spanish sp. Accepted pairs: <a href="https://developers.apptweak.com/reference/languages-1" target="_blank"><code>GET /api/public/apptweak/languages</code></a> with store=ios or store=android. Defaults to the country's <a href="https://developers.apptweak.com/reference/languages-overview#default-language" target="_blank"><b>default language</b></a>.

device'iphone' | 'ipad' | 'android'

Choose a device from iphone, ipad or android. Defaults to iphone.

start_datestring date

Start date (YYYY-MM-DD). Defaults to 30 days ago.

end_datestring date

End date (YYYY-MM-DD). Defaults to yesterday.

Response

Successful response.

resultobject

Changes

    • breaking

      for the query request parameter device, default value was changed from android to iphone

    • breaking

      for the query request parameter end_date, default value 2025-08-20 was removed

    • breaking

      for the query request parameter start_date, default value 2025-08-01 was removed

    • breaking

      for the query request parameter end_date, the format changed from no format to date

    • breaking

      for the query request parameter start_date, the format changed from no format to date

    • info

      api tag Keyword Metrics by App added

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status