Cross-Store ASO Keyword Rank Monitor

Know when your app gains or loses keyword visibility.

Monitor public Apple App Store and Google Play keyword rankings across countries. Scheduled runs remember the previous successful positions and return only meaningful changes: rank gains, drops, Top 3/10 transitions, lost rankings, competitor crossovers, and changes at #1.

This Actor is intentionally a focused rank monitor, not another full search-results scraper or an AppTweak/Appfigures/Sensor Tower replacement.

What it does

One HTTP search is made for each store × country × keyword. Every app in that result is then matched against all relevant tracked apps by stable ID:

• Apple apps are matched by numeric App Store ID.
• Google Play apps are matched by package name.
• App titles are never used as identity.
• No login, API key, browser, proxy, LLM, Apple developer account, or Play Console account is required.

With 10 keywords, 3 countries, and both stores, the Actor performs 60 searches—not one search per tracked app.

Use cases

ASO monitoring

Track important keywords daily or several times per day with Apify Schedules.

Release and metadata impact

See whether title, subtitle, or description changes coincide with ranking movement.

Competitor monitoring

Mark explicitly tracked apps as competitor and detect when one crosses above or below your app.

Country monitoring

Find markets where keyword visibility improves or deteriorates.

Agency monitoring

Track multiple client apps without buying a full ASO SaaS suite.

Input

{
  "apps": [
    {
      "name": "HabitKit",
      "role": "own",
      "appStoreId": "6448311069",
      "googlePlayId": "com.roehl.habitkit"
    },
    {
      "name": "Competitor",
      "role": "competitor",
      "appStoreId": "123456789",
      "googlePlayId": "com.example.competitor"
    }
  ],
  "keywords": ["habit tracker", "daily habits"],
  "countries": ["us", "gb", "de"],
  "stores": ["appstore", "googleplay"],
  "googlePlayLanguage": "en",
  "maxResultsPerKeyword": 30,
  "onlyChanges": true,
  "minimumRankChange": 2
}

Each logical app needs name, role, and at least one store ID. Cross-store IDs are not inferred. Country values are two-letter codes. Search depth is capped at 30 because Google Play's public HTTP result depth is more limited than Apple's.

Change-only mode

onlyChanges defaults to true. The default Dataset then contains incident rows rather than another full result dump.

{
  "eventId": "2d0a...",
  "eventType": "ENTERED_TOP_10",
  "severity": "MEDIUM",
  "store": "appstore",
  "country": "us",
  "keyword": "habit tracker",
  "appName": "HabitKit",
  "appId": "6448311069",
  "role": "own",
  "previousRank": 14,
  "currentRank": 8,
  "rankChange": 6,
  "checkedDepth": 30,
  "checkedAt": "2026-08-29T10:00:00.000Z",
  "baselineRun": false
}

The Actor can emit:

• RANK_GAIN, RANK_DROP
• ENTERED_TOP_3, LEFT_TOP_3
• ENTERED_TOP_10, LEFT_TOP_10
• ENTERED_RESULTS, DROPPED_OUT
• COMPETITOR_OVERTAKE, COMPETITOR_OVERTAKEN
• TOP_APP_CHANGED

Ordinary gains and drops smaller than minimumRankChange are suppressed. Boundary, entry, and drop-out events are still emitted. Event IDs are deterministic and duplicate events are removed within a run.

Rank semantics

rankChange = previousRank - currentRank.

• #9 → #4 is +5 and means improvement.
• #4 → #9 is -5 and means deterioration.

A null rank is never converted to depth + 1. For example:

{
  "found": false,
  "rank": null,
  "checkedDepth": 30
}

This means not found within the first 30 checked results. It does not claim that the app is ranked #31 or lower.

Baseline and persistent state

The first successful run for a tracked tuple establishes its baseline. It saves rank and #1 state in the named Apify Key-Value Store cross-store-aso-rank-monitor-state and writes baselineRun: true to the OUTPUT summary. With onlyChanges=true, an all-new baseline normally produces zero Dataset rows.

Later scheduled runs compare against the last trustworthy state. State keys are deterministic from store | country | keyword | appId; top-app state uses store | country | keyword.

Do not overlap runs of the same configuration. The MVP uses one state document and concurrent writes from overlapping runs can race.

Snapshot mode

Set onlyChanges to false for one normalized snapshot per app × keyword × country × store. A not-found snapshot retains rank: null, found: false, and the checked depth. Change detection and state updates still run normally.

Failure safety

Apple and Google responses are shape-validated before any app is considered absent. In particular, a Google page with no confidently parsed app cards is a failed job, not an empty ranking.

• 429, temporary 5xx, and network/timeout failures receive limited exponential-backoff retries.
• A failed keyword market is listed under errors in OUTPUT.
• Other keyword markets continue.
• Failed jobs do not update rank or top-app state.
• If every job fails, the run fails and no state is committed.

Output summary

The default Key-Value Store OUTPUT record includes run status, baseline status, planned/succeeded/failed jobs, rank checks, detected event totals, event-type counts, timestamps, and per-job errors.

{
  "status": "SUCCEEDED",
  "baselineRun": false,
  "appsTracked": 4,
  "keywords": 20,
  "countries": 3,
  "stores": 2,
  "searchJobsPlanned": 120,
  "searchJobsSucceeded": 118,
  "searchJobsFailed": 2,
  "rankChecks": 472,
  "eventsDetected": 17,
  "errors": []
}

Extraction approach

Apple uses the public iTunes Search API with country, software entity, and a bounded result limit. Result array order is treated as the public storefront search order. Calls are throttled in line with Apple's documented approximate API limit.

Google Play uses the public server-rendered search HTML. Ordered app detail cards are parsed by package ID, deduplicated, shape-checked, and bounded before ranks are accepted. There is no automatic browser or proxy fallback; unexpected page structure fails clearly.

Pay-per-event readiness

The billing adapter has one clean event: keyword_market_checked. One event means one successfully parsed store × country × keyword search, regardless of how many tracked apps were evaluated. It does not charge again per app or detected incident.

No final event price is declared in this repository. Pricing must be configured and reviewed in Apify Console before Store publication. When the current Actor pricing model is not PPE, the adapter is a no-op.

Local development

Requires Node.js 20 or newer.

npm install
npm test
npm run build
npm run validate:live

The live validation performs two keywords × two countries × both stores twice, reports ranks and result counts, and checks Top 10 repeatability. It uses public HTTP only.

Known limitations

• Public rankings can differ from personalized results on a specific device or user account.
• Apple ranks represent Apple's public storefront Search API response, which can differ from the App Store UI.
• Google Play public search depth is more limited than Apple's.
• “Not found” means not found within the configured checked depth.
• Google Play's public page and private internal structure may change; parser breakage becomes a job error rather than a false drop-out.
• This Actor measures keyword rank, not keyword search volume.
• It does not estimate downloads or revenue.
• It does not calculate keyword difficulty.
• It does not perform automatic competitor or keyword discovery.
• It is not intended to replace AppTweak, Appfigures, Sensor Tower, or a full ASO audit platform.

Data and privacy

Input contains public app IDs and keyword markets. No credentials or user cookies are requested. Persistent ranking history remains in the Actor user's Apify Key-Value Store.