> ## Documentation Index > Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt > Use this file to discover all available pages before exploring further. # Competitors and market data > Keep competitors' listings, your category chart rank and your own analytics and revenue as files, so every change starts from the same facts. A listing change is a guess until you know what the apps around you do and how your own numbers move. These commands write competitors, your category rank and your analytics and revenue into the repo, so you and your agent decide from files instead of from memory. ## What needs a key | Command | Without an Appeeky key | With `APPEEKY_API_KEY` | | - | - | - | | `competitors discover`, `competitors pull` | Not available | Works | | `category pull` | App Store chart | App Store and Google Play charts | | `data pull` | Attribution files only, with a self-hosted [attribution](https://docs.appeeky.com/docs/spec-attribution.md) server | Store analytics, sales, Apple Search Ads, RevenueCat, Meta, TikTok and attribution | | `coverage`, `suggest` | Work, not weighted by popularity | Ranked by search popularity, plus keyword opportunities | ## Find competitors ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec competitors discover # 1234567891 Calm Night 4.7★ 52310 # 1234567892 Hush: White Noise 4.6★ 18744 # 1234567893 Rain Rain Sleep 4.8★ 9120 # # Add them with --add , or by hand under competitors: in appeeky.spec.yaml. ``` `discover` lists apps like yours in the first storefront under `targets`. `--store google-play` looks on Google Play instead. `--add 3` writes the first three you do not have yet into the spec: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} competitors: - name: Calm Night appStore: "1234567891" # numeric App Store id googlePlay: com.calmnight.app # optional: the same app on Google Play ``` ## Pull competitors ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec competitors pull # ✓ appeeky/competitors/calm-night.yaml # changed App Store: title "Calm Night: Sleep" → "Calm Night: Rain & Baby Sleep" # changed App Store: now #6 for "baby sleep" (was #12) # ✓ appeeky/competitors/hush-white-noise.yaml # # The git diff shows what each competitor changed since the last pull. ``` Each competitor gets one file, per store: | Field | What it holds | | - | - | | `title`, `developer`, `rating`, `ratings` | The listing as it is today | | `version`, `updated`, `releaseNotes` | The latest version and its notes | | `description` | The first 600 characters of the description | | `ranks` | The 25 searches it ranks best for in your first targets storefront, with popularity | | `yourTargets` | Where it ranks for your own targets | | `recentReviews` | How many recent reviews, their average, and up to five low ratings | Every pull compares with the one before and adds what changed to `appeeky/competitors/changes.md`, newest first: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} - 2026-11-01 · Calm Night · App Store: title "Calm Night: Sleep" → "Calm Night: Rain & Baby Sleep" - 2026-11-01 · Calm Night · App Store: now #6 for "baby sleep" (was #12) - 2026-10-18 · Calm Night · App Store: version 5.2: Fan and AC sounds, a new bedtime timer ``` A change is a new title, a new version, a rewritten description, or a climb into the top 10 for one of your targets. `status` warns when a competitor changed something while one of your releases was being measured, because their move can explain yours. ## Category rank ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec category pull # App Store US top-free · Health & Fitness #42 ▲3 since 2026-11-07 # App Store GB top-free · Health & Fitness not in the top 100 # # Recorded in appeeky/category.csv. verify reads it as category_rank. ``` `category pull` adds one row a day per store and storefront to `appeeky/category.csv`. On the App Store the category and chart come from the app (a paid app is read from top paid), with no key. Google Play needs `APPEEKY_API_KEY` and the category: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} category: googlePlay: HEALTH_AND_FITNESS # appStore: "6013" to override the App Store genre chart: top-free # top-free | top-paid | top-grossing countries: [us, gb] # default: the storefronts under targets ``` Charts list the top 100. Below that, the rank is empty. The rank is public, so the file is committed with the spec. `verify` reads it as `category_rank` (lower is better) once there are two days of history in a window, and when no target moved and there are no analytics, the category rank decides a release. Run it daily so there is a history before each push; the daily workflow does. ## Analytics and revenue ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec data pull --days 90 # ✓ .appeeky/data/app-store-analytics.csv 90 rows 2026-08-10 → 2026-11-07 # ✓ .appeeky/data/revenuecat.csv 90 rows 2026-08-10 → 2026-11-07 # ✓ .appeeky/data/attribution-sources.csv 14 rows # # In .appeeky/data/ (gitignored). Set data: { commit: true } in appeeky.spec.yaml to version it with the spec. ``` | File | From | | - | - | | `app-store-analytics.csv`, `google-play-analytics.csv` | Impressions, page views, downloads, conversion, proceeds, trials, subscriptions per day | | `app-store-traffic-sources.csv` | Where product page views came from | | `app-store-sales.csv`, `app-store-countries.csv` | App Store Connect sales reports, by day and by country | | `apple-search-ads.csv` | Spend, impressions, taps, installs | | `revenuecat.csv` | Revenue, MRR, trials, new customers, trial conversion, churn, actives | | `meta-ads.csv`, `tiktok-ads.csv` | The campaigns under `ads:`, per day | | `attribution-*.csv`, `smart-links.csv` | Installs and revenue by source, keyword, campaign, country and link ([Attribution](https://docs.appeeky.com/docs/spec-attribution.md)) | Each source comes from the connections in Appeeky: connect your stores, Search Ads, RevenueCat, Meta and TikTok there first. A source that fails is listed with its error; the rest are still written. `--days` sets how far back (default 90, up to yesterday). Daily files are merged by date on every pull, so a scheduled pull keeps one growing file per source. A `README.md` index next to them says what each file holds and which dates it covers. These are your private business numbers, so they stay in the gitignored `.appeeky/data/` unless you set `data: { commit: true }`, which writes them to `appeeky/data/`, for example in a private repo. ## Keyword popularity With `APPEEKY_API_KEY`, `coverage` ranks your targets by search popularity and difficulty, and `suggest` adds keyword opportunities for the app with their popularity. Results are cached for 7 days in `.appeeky/cache/`. Competitor files carry popularity for the searches they rank for, so an agent can compare them with your targets. See [Listing](https://docs.appeeky.com/docs/spec-listing.md). ## How agents use them Agents read these files before they propose anything. The `appeeky-aso` specialist reads competitors and the category chart, the `appeeky-reviews` specialist reads competitors' low ratings, and the ads specialist reads the data files. No CI is needed: an agent runs `competitors pull` or `data pull` when it needs fresh numbers. Related: [Reviews](https://docs.appeeky.com/docs/spec-reviews.md) · [Attribution](https://docs.appeeky.com/docs/spec-attribution.md) · [On your own keys](https://docs.appeeky.com/docs/spec-own-keys.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.