API Reference
My API token 🔑

Keyword Metrics by App

KPIs that are specific to a keyword and an app.

👍

Improved Keyword Installs starting July 17, 2025

Starting July 17, 2025, we're updating our keyword installs estimates. This change will make keyword performance trends even more precise, especially when looking at historical data.

Keyword Metrics by App are KPIs that AppTweak has been able to gather or estimate about keywords. See below for a list of available metrics.

Metric nameDescriptionOriginHistorical Data Available?
rankThe position of the queried app in the search result list when a specific keyword is searched for.Gathered directly from the stores✅
installsNumber of users that search for this keyword and then install the queried appAppTweak estimates✅
chanceA score between 1 and 100 that indicates how likely your app is to rank in the top 10 search results for the selected keyword.AppTweak-defined KPI➖
keiKEI (Keyword Efficiency Index): A score that indicates the visibility potential of a keyword, taking into account keyword volume and chance score.AppTweak-defined KPI➖
relevancyThe relevancy score is an indicator between 0 and 100, indicating how relevant a keyword is for your app. A higher score indicates higher relevancy. The relevancy score is based on the app store ranking algorithm, hence targeting highly relevant keywords ensures that your app shows up when users search for the solution you offer.AppTweak-defined KPI➖

📘

How are Keyword Installs computed?

Keyword Installs are an estimated number of organic installed received by an app from a keyword. They are based on:

  • current or historical app ranking on a keyword
  • current keyword volume

App Keyword Ranking Current takes into account the today's app ranking and today's keyword volume to provide a keyword install estimation.

App Keyword Ranking Historical takes into account the historical app ranking and today's keyword volume to provide a keyword install estimation. This means that the historical keyword installs may vary if your keyword volume evolve through time. Therefore we recommend fetching data regularly and save it to have a more accurate picture.

This information is exposed through two endpoints:

  • The Current endpoint which returns the latest - most recent - data available
  • The History endpoint which returns the historical daily values over a given period of time

Rules for missing data in historical endpoints

When we don't have historical data for some days, we try to come up with our best estimate for that day. This estimate is exposed in a field called effective_value. It's useful because it's guaranteed to always return a number, so it won't break a dashboard or pipeline you might have built expecting a value every day. The same logic is used in the AppTweak tool itself.

⚠️

effective_value can differ between requests for the same day

effective_value is estimated using the other days within the date range you queried — it never looks outside your start_date/end_date. This means that querying the same day with a wider or narrower range can return a different effective_value for that same day, if it changes which neighboring days are available to estimate from.

If you need a number for a given day that's stable regardless of the range you query, use value instead, and treat null as "no estimate available" rather than defaulting it to 0 yourself.

The exact estimation logic differs slightly by metric — see the examples below.

📘

Ranked, unranked or no data

{
  "date": "2024-03-11",
  "value": null,
  "fetch_performed": true,
  "effective_value": 501
}

To know whether your app is ranked on a keyword or not, you can refer to the following logic in the response data:

  • value = non-null and fetch_performed = true ➔ ranked
  • value = null and fetch_performed = true ➔ unranked
  • value = null and fetch_performed = false ➔ no data

In addition to value, you can useeffective_value, that corresponds to a value that is guaranteed to be non-null. The logic to compute effective_value is:

  • If value is not null, effective_value = value
  • Otherwise
    • If fetch_performed = true, then effective_value = 501, corresponding to the numeric representation of unranked
    • 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 value for the effective_value (use an average if 2 days are at the same distance to the missing day)
      • Otherwise, defaults to 501

📘

Installs & estimates

{
  "date": "2024-03-11",
  "value": null,
  "effective_value": 8234
}

fetch_performedis not returned for installs — it only applies to rank. For installs, value is simply null on any day where we have no ranking data for that keyword (since installs are derived from rank), with no "ranked/unranked" distinction.

The logic to compute effective_value for installs is:

  • If value is not null, effective_value = value
  • Otherwise, look at the other days within the date range you queried. If at least one of them has a non-null value, effective_value is set to the value of the closest such day (averaging the two closest days if they're equidistant).
  • If no day in the queried range has a non-null value, effective_value defaults to 0.

Note: because the neighbor lookup in step 2 only considers days inside the start_date/end_date you queried, effective_value for a given day can differ between two requests that use the same start_date but a different end_date (or vice versa) — widening the range can surface a real data point that a narrower range wouldn't have found. value is unaffected by this and is always the same for a given day regardless of the range queried.


FAQs

How do I check which app store keywords my app ranks for via API?

You can pull an app's rank across a list of keywords with AppTweak's Keyword Metrics by App endpoint (GET /apps/keywords-rankings/current.json), passing an app id in apps and up to 5 keywords in keywords. The response nests results by app id, then by keyword, with a rank object per keyword showing the app's current search-result position, plus fetch_performed to confirm the app store was actually checked that day. Add installs, chance, kei, or relevancy to the metrics parameter to get visibility and opportunity scoring alongside the rank.

What's the difference between Keyword Metrics and Keyword Metrics by App?

The difference is whether the data is tied to a specific app: Keyword Metrics describes a keyword on its own, while Keyword Metrics by App describes how one app performs on that keyword. AppTweak's Keyword Metrics endpoint (GET /keywords/metrics/current.json) returns keyword-only figures like volume and difficulty that apply to any app searching for that term. Keyword Metrics by App (GET /apps/keywords-rankings/current.json) requires both an apps id and a keywords list, and returns app-specific fields — rank, installs, chance, kei, relevancy — for that exact app-keyword pair.

How do I pull bulk app keyword ranking data across iOS and Android for the same app?

AppTweak's Keyword Metrics by App endpoint accepts a device parameter (iphone, ipad, or android) alongside up to 5 keywords and 5 apps per call, so you can pull the same app's ranking data for both platforms by switching device across two requests. Combine this with the History endpoint (GET /apps/keywords-rankings/history.json) and a start_date/end_date range to build a bulk, cross-platform view of keyword performance over time rather than checking each keyword one at a time.

How do I tell if my app is ranked, unranked, or has no data for a keyword via API?

AppTweak's Keyword Metrics by App endpoint distinguishes these three states through the value and fetch_performed fields on rank. A non-null value with fetch_performed: true means the app is ranked at that position. A null value with fetch_performed: true means the store was checked but the app didn't appear in the results — unranked. A null value with fetch_performed: false means no fetch happened, so there's no data either way. The effective_value field (for example 501 for unranked) always returns a number, useful when a dashboard needs a non-null value to plot.

Can I estimate how many installs a keyword drives for a specific app?

Yes — AppTweak's Keyword Metrics by App endpoint returns an installs field per app-keyword pair, estimating organic installs the app receives from that keyword based on its ranking and the keyword's search volume. On the Current endpoint this uses today's rank and today's volume; on the History endpoint it combines the historical rank for each day with today's volume, so a past day's install estimate can shift if you re-query after the keyword's volume has changed — query regularly and store the results if you need a stable historical record.

What does the KEI (Keyword Efficiency Index) score returned by this endpoint mean?

KEI is a score AppTweak's Keyword Metrics by App endpoint returns to indicate a keyword's visibility potential for a given app, combining keyword volume with the app's chance score. A high KEI points to a keyword that's both searched often and realistically within reach for that app to rank on, making it useful for shortlisting which keywords to prioritize out of a larger candidate list rather than optimizing purely for high-volume terms the app is unlikely to rank for.

Updated 8 days ago

Updated 8 days ago