DEV Community: Fekri

An App Store MCP Server in TypeScript: Wrapping Apple's Search API for Claude and Cursor, and the Walls You'll Hit (2026)

Fekri — Mon, 09 Nov 2026 08:23:03 +0000

Claude, Cursor and Claude Code can reason about App Store data, but they can't see the App Store. Ask "who shows up for habit tracker in the UK?" and you get a guess. With the Model Context Protocol (MCP), you write a small server that exposes tools, the host starts it, and the model calls those tools when it needs real data.

This post builds one in TypeScript. It wraps Apple's public iTunes Search API and Lookup API, which need no key and no account, and it exposes two tools:

search_apps(term, country, limit) returns apps in the order the Search API gives them, with id, name, developer and rating count.
lookup_app(ids, country) returns public listing facts for up to 20 app ids.

It runs over stdio, validates input with zod, paces and caches its calls to Apple, and backs off on 403 and 429. I ran everything below on November 9, 2026, on Node 20.19.2, against the live API in the US and GB storefronts.

Which SDK package?

The first wall comes before any code. The package most tutorials use, @modelcontextprotocol/sdk, still shows latest: 1.32.2 on npm, but the SDK's README calls that the v1 maintenance line. v2 is the current stable release. It ships as @modelcontextprotocol/server and @modelcontextprotocol/client (2.4.0 when I installed them) and implements the 2026-07-28 spec. The imports and the stdio setup changed, so a 2025 tutorial won't compile against v2. I used v2.

mkdir appstore-mcp && cd appstore-mcp
npm init -y && npm pkg set type=module
npm install @modelcontextprotocol/server @modelcontextprotocol/client zod@^4.2.0
npm install -D typescript @types/node@20

My tsconfig.json uses "module": "NodeNext", "outDir": "build" and "strict": true. npm gave me TypeScript 7.0.2, which failed with Cannot find name 'process' until I added "types": ["node"].

Part 1: talking to Apple politely

Every call to Apple goes through one function. It checks a one-hour in-memory cache, runs calls one at a time, waits at least 3 seconds between them, and retries 403, 429, 5xx and network errors with exponential back-off (or Retry-After, if Apple sends it).

// App Store MCP server: wraps Apple's public iTunes Search + Lookup APIs over stdio.
// Rule #1 of stdio servers: stdout is the JSON-RPC channel. Log with console.error only.
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const BASE = process.env.APPLE_BASE ?? "https://itunes.apple.com"; // override only for the backoff test
const USER_AGENT = "appstore-mcp/0.1 (personal research tool)";
const MIN_GAP_MS = Number(process.env.MIN_GAP_MS ?? 3000); // ~20 calls/min max
const CACHE_TTL_MS = Number(process.env.CACHE_TTL_MS ?? 60 * 60 * 1000); // 1 hour
const MAX_RETRIES = 4;

const log = (...args: unknown[]) => console.error("[appstore-mcp]", ...args);
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

// --- polite HTTP: one request at a time, a gap between calls, cache, back-off ---
const cache = new Map<string, { at: number; data: any }>();
let lastCall = 0;
let queue: Promise<unknown> = Promise.resolve();

class AppleError extends Error {
  constructor(message: string, readonly status: number) {
    super(message);
  }
}

async function appleGet(path: string, params: Record<string, string>): Promise<any> {
  const url = `${BASE}${path}?${new URLSearchParams(params)}`;
  const hit = cache.get(url);
  if (hit && Date.now() - hit.at < CACHE_TTL_MS) {
    log("cache hit", url);
    return hit.data;
  }
  // Serialize calls so parallel tool calls from the model don't burst Apple.
  const run = queue.then(() => fetchWithBackoff(url));
  queue = run.catch(() => undefined);
  const data = await run;
  cache.set(url, { at: Date.now(), data });
  return data;
}

async function fetchWithBackoff(url: string): Promise<any> {
  for (let attempt = 0; ; attempt++) {
    const wait = lastCall + MIN_GAP_MS - Date.now();
    if (wait > 0) await sleep(wait);
    lastCall = Date.now();

    let res: Response;
    try {
      res = await fetch(url, {
        headers: { "User-Agent": USER_AGENT },
        signal: AbortSignal.timeout(15_000),
      });
    } catch (err) {
      if (attempt >= MAX_RETRIES) throw new AppleError(`network error: ${err}`, 0);
      await backoff(attempt, null, "network error");
      continue;
    }

    if (res.ok) {
      // Apple sends JSON as text/javascript with leading blank lines; parse text, not res.json().
      const text = await res.text();
      log(`GET ${url} -> ${res.status} (${text.length} bytes, attempt ${attempt + 1})`);
      return JSON.parse(text);
    }
    const retryable = res.status === 403 || res.status === 429 || res.status >= 500;
    if (!retryable || attempt >= MAX_RETRIES) {
      throw new AppleError(`Apple returned HTTP ${res.status} for ${url}`, res.status);
    }
    await backoff(attempt, res.headers.get("retry-after"), `HTTP ${res.status}`);
  }
}

async function backoff(attempt: number, retryAfter: string | null, why: string) {
  const fromHeader = retryAfter ? Number(retryAfter) * 1000 : NaN;
  const ms = Number.isFinite(fromHeader)
    ? fromHeader
    : Math.min(60_000, 2_000 * 2 ** attempt) + Math.random() * 1000;
  log(`${why}, backing off ${Math.round(ms)} ms (attempt ${attempt + 1})`);
  await sleep(ms);
}

Every log line goes through console.error (see wall 1). Apple also sends the JSON as text/javascript with blank lines before the opening brace, so I parse the text myself.

Part 2: shaping what the model sees

Apple returns a lot per app: screenshot URLs, the full description, release notes, device lists. A model needs little of it, and every character costs context. So the server keeps a few fields:

// --- shaping: return only what a model needs, not Apple's 10 KB per app ---
function slim(app: any) {
  return {
    id: app.trackId,
    name: app.trackName,
    developer: app.artistName,
    rating_count: app.userRatingCount ?? null,
    avg_rating: app.averageUserRating != null ? Number(app.averageUserRating.toFixed(2)) : null,
    price: app.formattedPrice ?? null,
    genre: app.primaryGenreName,
  };
}

const country = z
  .string()
  .regex(/^[a-zA-Z]{2}$/, "two-letter storefront code, e.g. us, gb, de")
  .transform((c) => c.toLowerCase())
  .default("us")
  .describe("App Store storefront, ISO 3166-1 alpha-2 (us, gb, de, jp...). Results differ per storefront.");

const textResult = (data: unknown) => ({
  content: [{ type: "text" as const, text: JSON.stringify(data) }],
  structuredContent: data as Record<string, unknown>,
});

const errorResult = (err: unknown) => ({
  isError: true,
  content: [{ type: "text" as const, text: err instanceof Error ? err.message : String(err) }],
});

structuredContent gives clients a typed object. The text block is there for hosts that only read text.

Part 3: the tools

function buildServer() {
  const server = new McpServer({ name: "appstore", version: "0.1.0" });

  server.registerTool(
    "search_apps",
    {
      title: "Search the App Store",
      description:
        "Search iOS apps in one App Store storefront via Apple's public Search API. " +
        "Returns apps in the order the API returned them ('position'). " +
        "That order is NOT the official App Store search rank; call it an observed search API position.",
      inputSchema: z.object({
        term: z.string().min(1).max(100).describe("Search phrase, e.g. 'habit tracker'"),
        country,
        limit: z.number().int().min(1).max(50).default(10).describe("How many results, 1-50"),
      }),
      annotations: { readOnlyHint: true, openWorldHint: true },
    },
    async ({ term, country, limit }) => {
      try {
        const data = await appleGet("/search", {
          term, country, entity: "software", limit: String(limit),
        });
        return textResult({
          term,
          country,
          checked_at: new Date().toISOString(),
          source: "itunes.apple.com/search (observed API order, not official rank)",
          requested: limit,
          returned: data.results.length, // Apple often returns fewer than you asked for
          results: data.results.map((app: any, i: number) => ({ position: i + 1, ...slim(app) })),
        });
      } catch (err) {
        return errorResult(err);
      }
    },
  );

  server.registerTool(
    "lookup_app",
    {
      title: "Look up App Store apps by id",
      description:
        "Fetch public listing facts for 1-20 iOS app ids in one storefront via Apple's Lookup API. " +
        "Ids not sold in that storefront are listed in 'missing_ids'.",
      inputSchema: z.object({
        ids: z.array(z.number().int().positive()).min(1).max(20).describe("Numeric App Store ids"),
        country,
      }),
      annotations: { readOnlyHint: true, openWorldHint: true },
    },
    async ({ ids, country }) => {
      try {
        const data = await appleGet("/lookup", { id: ids.join(","), country, entity: "software" });
        const apps = data.results
          .filter((r: any) => r.wrapperType === "software")
          .map((app: any) => ({
            ...slim(app),
            version: app.version,
            current_version_date: app.currentVersionReleaseDate,
            first_release_date: app.releaseDate,
            min_ios: app.minimumOsVersion,
            content_rating: app.contentAdvisoryRating,
            bundle_id: app.bundleId,
          }));
        const found = new Set(apps.map((a: any) => a.id));
        return textResult({
          country,
          checked_at: new Date().toISOString(),
          apps,
          missing_ids: ids.filter((id) => !found.has(id)),
        });
      } catch (err) {
        return errorResult(err);
      }
    },
  );

  return server;
}

serveStdio(buildServer);
log(`ready on stdio (min gap ${MIN_GAP_MS} ms, cache ${CACHE_TTL_MS / 1000} s)`);

The model only knows a tool from its name, description and schema, so the descriptions matter most. I put the "not an official rank" warning there so the model repeats it in its answer.

Testing it without a model

You don't need a model to test an MCP server. The v2 client can start it as a child process and call it. My src/test-client.ts, shortened:

import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

const client = new Client({ name: "appstore-test-client", version: "0.1.0" },
  { versionNegotiation: { mode: (process.argv[2] ?? "auto") as "auto" | "legacy" } });
const transport = new StdioClientTransport({ command: process.execPath, args: ["build/server.js"] });

try {
  await client.connect(transport);
  console.log("era:", client.getProtocolEra(), client.getNegotiatedProtocolVersion());
  const { tools } = await client.listTools();
  for (const t of tools) console.log(t.name, JSON.stringify(t).length, "chars");

  for (const country of ["us", "gb"]) {
    const r: any = await client.callTool({ name: "search_apps", arguments: { term: "habit tracker", country, limit: 10 } });
    const ids = r.structuredContent.results.slice(0, 3).map((a: any) => a.id);
    await client.callTool({ name: "lookup_app", arguments: { ids: [...ids, 1], country } });
  }
  // bad input comes back as isError, not as an exception
  await client.callTool({ name: "search_apps", arguments: { term: "x", country: "usa", limit: 500 } });
} finally {
  await client.close();
}

Run it with npx tsc && node build/test-client.js. Here is part of the real output from the US storefront:

connected: appstore, era=modern, protocol=2026-07-28
tool search_apps: 856 chars of definition
tool lookup_app: 733 chars of definition
[appstore-mcp] GET .../search?term=habit+tracker&country=us&entity=software&limit=10 -> 200 (92401 bytes, attempt 1)

## search_apps {"term":"habit tracker","country":"us","limit":10} -> ok in 112 ms, 1773 chars
requested 10, returned 9
 1. Habit Tracker (1438388363) by InnerGrow, 148696 ratings, 4.79
 2. Habit Tracker - HabitKit (6443918070) by Sebastian Roehl, 2555 ratings, 4.84
 3. Onrise: Habit Tracker & Focus (1547137474) by Maximilian Munker, 2613 ratings, 4.84
 4. Finch: Self-Care Pet (1528595748) by Finch Care Public Benefit Corporation, 773252 ratings, 4.95
 ...
## lookup_app {"ids":[1438388363,6443918070,1547137474,1],"country":"us"} -> ok in 2920 ms, 1083 chars
Habit Tracker: v2.15.12 (2026-11-07), 148716 ratings, Free
missing_ids: [1]

## search_apps {"term":"habit tracker","country":"usa","limit":500} -> ERROR in 2 ms
Input validation error: Invalid arguments for tool search_apps: country: two-letter storefront code, e.g. us, gb, de, limit: Too big: expected number to be <=50

With node build/test-client.js legacy, the same server answered on the older handshake (era=legacy, protocol=2025-11-25). serveStdio serves both from one factory, so hosts on the 2025 protocol still work.

Plugging it into a host

Build it, then point the host at the absolute path of build/server.js. For Claude Code:

claude mcp add appstore -- node /absolute/path/appstore-mcp/build/server.js
claude mcp list   # appstore: node .../build/server.js - âœ” Connected

Cursor (~/.cursor/mcp.json) and Claude Desktop (claude_desktop_config.json) use the same mcpServers shape:

{
  "mcpServers": {
    "appstore": { "command": "node", "args": ["/absolute/path/appstore-mcp/build/server.js"] }
  }
}

I checked the connection in Claude Code 2.1.312. I didn't test Cursor or Claude Desktop for this post, so check their MCP settings if the file location has moved.

The walls you'll hit

1. stdout is the wire. Over stdio, every line on stdout is read as JSON-RPC. I tested a copy of the server that prints one line before it starts. The v2 client skipped a plain-text line, but a console.log(JSON.stringify({ level: "debug", ... })) line raised a schema error on the transport (invalid_union ... expected "2.0"). The SDK's troubleshooting page says hosts report stray lines as SyntaxError: Unexpected token ... is not valid JSON. Log with console.error, and watch for dependencies that print.

2. "Position" is not an App Store rank. It is just the order the Search API returned. Apple doesn't document how that order relates to what people see in the App Store app. The API also returned fewer results than I asked for: limit=10 gave 9, limit=25 gave 23, limit=50 gave 48. The tool reports requested and returned so the model doesn't talk about a tenth app that isn't there.

3. Storefronts are separate stores. In GB, Finch dropped out of the top nine, and Dots and Structured came in. App 6480042457 was "Habit Tracker - Daily Goals" in the US and "Routine Planner & Daily Habits" in GB. InnerGrow's Habit Tracker had 148,696 ratings in the US and 23,203 in GB, because ratings are per storefront. An id not sold in a storefront just disappears, so the server lists it in missing_ids. An unknown country like xx returns HTTP 400, which the server doesn't retry.

4. Rate limits are real, even when you can't see them. Apple's Search API documentation says it is "limited to approximately 20 calls per minute (subject to change)". One burst of 40 calls with no delay returned HTTP 200 all 40 times, in 12.7 seconds. That only means the limit didn't trigger for me today. A model can fire many tool calls in a row, so the server queues them with a 3-second gap, about 20 per minute. I tested the retry path against a local fake server that answered 429, then 403, then 200: the tool returned a normal result after 6.7 seconds.

5. Caching happens on both sides. Apple's responses carried cache-control: max-age=86400. The search said 148,696 ratings for InnerGrow's Habit Tracker, and the lookup a few seconds later said 148,716. Record checked_at and don't treat numbers as live. I cache text facts for an hour. Apple's terms say promotional content such as app icons must not be "downloaded, saved, cached", so the server doesn't return artwork. Read the terms yourself.

6. Every token counts. Apple sent 92,401 characters for nine apps. The trimmed result was 1,773, about 50 times smaller. The two tool definitions add 856 and 733 characters to every conversation that loads the server. Keep descriptions short and exact, return ids so the model can call lookup_app instead of guessing, and never pass Apple's raw JSON through.

Where PeekPanda saves time

This server answers one question well: what the public API shows right now, in one storefront. It has no memory. It can't tell you how a position moved last week, how hard a keyword is, or which ads a rival runs.

That's the gap I built PeekPanda* for. It's an iOS competitor catalogue where every app has a case file of dated, stored evidence: observed search positions with directional popularity and difficulty signals, keyword gap against a rival, stored App Store charts, dated paid-ad observations, matched organic content, and download and revenue estimates labelled as estimates. It also runs a hosted MCP server that Claude Code, Codex and Cursor can connect to with OAuth sign-in or an API key. Its documented tools include search_apps, get_app, get_ads and aso, so your agent reads the same stored history you see, without you running collectors.

Wrap-up

Two tools, zod schemas and serveStdio take about 200 lines.
Use the v2 packages, log to stderr, and test with the SDK client before you open a host.
Be honest in tool output: observed positions, per-storefront data, checked_at, and what's missing.
Pace, cache and back off, even when Apple seems not to mind.

Ask your assistant who shows up for your main keyword in a few storefronts. In my test, the US and GB top nine already differed by two apps.

*I build it.

App Store Listing Audits in PHP: Lookup API Checks for Titles, Screenshots and Release Notes, and the Walls You'll Hit (2026)

Fekri — Mon, 02 Nov 2026 08:25:40 +0000

Most App Store listing advice is a checklist: use your 30 title characters, fill the screenshot slots, localize, write real release notes. The checklist is easy. Running it against your own listing, in every storefront, next to your rivals, is the part people skip.

This post builds a small PHP command-line tool that does it. You give it your app id and a few rival ids. It pulls the public listing from Apple's iTunes Lookup API, runs about a dozen checks, prints a side-by-side table per storefront, and can write JSON for later. One file, around 100 lines, no framework, no Composer packages.

I ran everything below on PHP 8.5 CLI against the live API on November 2, 2026. The output in this post is what I got. You need PHP 8.3 or newer (for mb_str_pad) with the curl and mbstring extensions.

The data source

The Lookup API takes one or more App Store ids and returns public listing data as JSON. No key, no account:

https://itunes.apple.com/lookup?id=1111447047,963034692&country=us&entity=software

The id is the number at the end of an app's store URL (apps.apple.com/us/app/.../id963034692). country picks the storefront. Several ids, comma separated, come back in one response, so one request per storefront is enough.

The fields this audit uses are trackName, description, releaseNotes, version, currentVersionReleaseDate, screenshotUrls, ipadScreenshotUrls, features, languageCodesISO2A, averageUserRating, userRatingCount, contentAdvisoryRating and formattedPrice.

The script

Save this as audit.php. The first id is your app, the rest are rivals.

<?php
// Audit public App Store listing metadata via Apple's iTunes Lookup API.
// Usage: php audit.php [--country=us,gb] [--json=out.json] YOUR_ID [RIVAL_ID ...]
declare(strict_types=1);

const LOOKUP = 'https://itunes.apple.com/lookup';
const UA = 'listing-audit/1.0 (+you@example.com)';

function lookup(array $ids, string $country, int $tries = 3): array {
    $url = LOOKUP . '?' . http_build_query(['id' => implode(',', $ids), 'country' => $country, 'entity' => 'software']);
    for ($i = 1; $i <= $tries; $i++) {
        $ch = curl_init($url);
        curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 20,
            CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_USERAGENT => UA]);
        $body = curl_exec($ch);
        $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        $err = curl_error($ch);
        if ($code === 200 && is_array($data = json_decode((string) $body, true))) {
            return array_column($data['results'] ?? [], null, 'trackId');
        }
        fwrite(STDERR, "[$country] try $i failed: HTTP $code $err\n");
        if ($code >= 400 && $code < 500 && !in_array($code, [403, 429], true)) break; // bad request: retrying won't help
        sleep(5 * $i); // back off: 403/429 here usually means "slow down"
    }
    throw new RuntimeException("lookup failed for $country");
}

function audit(array $a, DateTimeImmutable $now): array {
    $title = $a['trackName'];
    $desc = $a['description'] ?? '';
    $firstLine = trim(strtok($desc, "\n") ?: '');
    $notes = trim($a['releaseNotes'] ?? '');
    $days = $now->diff(new DateTimeImmutable($a['currentVersionReleaseDate']))->days;
    $iphone = count($a['screenshotUrls'] ?? []);
    $ipad = count($a['ipadScreenshotUrls'] ?? []);
    // supportedDevices lists iPads even for iPhone-only apps; this flag is the real signal.
    $universal = in_array('iosUniversal', $a['features'] ?? [], true);
    $langs = count($a['languageCodesISO2A'] ?? []);

    // Each row: label => [value shown, status]. Status: ok | warn | info.
    return [
        'Title' => [$title, 'info'],
        'Title chars' => [sprintf('%d/30 (%d bytes)', mb_strlen($title), strlen($title)),
            mb_strlen($title) > 30 ? 'warn' : (mb_strlen($title) < 20 ? 'info' : 'ok')],
        'Subtitle' => ['not in API', 'info'],
        'Description' => [mb_strlen($desc) . '/4000 chars', mb_strlen($desc) < 1000 ? 'warn' : 'ok'],
        'First line' => [mb_strimwidth($firstLine, 0, 48, '…'), $firstLine === '' ? 'warn' : 'info'],
        'iPhone shots' => ["$iphone/10", $iphone < 5 ? 'warn' : 'ok'],
        'iPad shots' => [$universal ? "$ipad/10" : 'n/a (iPhone-only)', $universal && $ipad < 3 ? 'warn' : 'ok'],
        'Languages' => [(string) $langs, $langs < 2 ? 'warn' : 'ok'],
        'Version' => [$a['version'] . " ({$days}d ago)", $days > 90 ? 'warn' : 'ok'],
        'Release notes' => [mb_strlen($notes) . ' chars',
            $notes === '' || preg_match('/^(bug fixes|minor|performance)[^\n]{0,60}$/i', $notes) ? 'warn' : 'ok'],
        'Rating' => [sprintf('%.2f (%s)', $a['averageUserRating'] ?? 0, number_format($a['userRatingCount'] ?? 0)),
            ($a['userRatingCount'] ?? 0) === 0 ? 'warn' : 'ok'],
        'Age rating' => [$a['contentAdvisoryRating'] ?? '?', 'info'],
        'Price' => [$a['formattedPrice'] ?? '?', 'info'],
    ];
}

function printTable(string $country, array $audits): void {
    $mark = ['ok' => ' ', 'warn' => '!', 'info' => ' '];
    echo "\n== Storefront: " . strtoupper($country) . " ==\n";
    $labels = array_keys(reset($audits));
    foreach ($labels as $label) {
        $cells = array_map(fn($rows) => $mark[$rows[$label][1]] . ' ' . $rows[$label][0], $audits);
        $cells = array_map(fn($c) => mb_str_pad(mb_strimwidth($c, 0, 34, '…'), 35), $cells);
        echo mb_str_pad($label, 15), implode('', $cells), "\n";
    }
}

$opts = getopt('', ['country:', 'json:'], $rest);
$ids = array_map('intval', array_slice($argv, $rest));
if (!$ids) {
    fwrite(STDERR, "usage: php audit.php [--country=us,gb] [--json=out.json] ID [ID ...]\n");
    exit(2);
}
$countries = explode(',', strtolower($opts['country'] ?? 'us'));
$now = new DateTimeImmutable('now', new DateTimeZone('UTC'));
$report = ['checked_at' => $now->format(DATE_ATOM), 'storefronts' => []];
$warnings = 0;

foreach ($countries as $n => $country) {
    if ($n > 0) sleep(3); // polite pause between storefronts
    try {
        $found = lookup($ids, $country);
    } catch (RuntimeException $e) {
        fwrite(STDERR, $e->getMessage() . "\n");
        exit(3);
    }
    $audits = [];
    foreach ($ids as $id) {
        if (!isset($found[$id])) {
            fwrite(STDERR, "[$country] $id not returned (wrong id, or not sold here)\n");
            continue;
        }
        $audits[$id] = audit($found[$id], $now);
        $warnings += count(array_filter($audits[$id], fn($r) => $r[1] === 'warn'));
    }
    if ($audits) printTable($country, $audits);
    $report['storefronts'][$country] = $audits;
}

if (isset($opts['json'])) {
    file_put_contents($opts['json'], json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) . "\n");
}
echo "\n$warnings warning(s). '!' marks a check worth a look.\n";
exit($warnings > 0 ? 1 : 0);

A few notes on the design.

Status, not score. Each row is ok, warn or info. I tried a 0-100 "listing score" first, and it was useless: a number hides which check failed. A ! next to one cell tells you exactly what to look at.

The thresholds are mine. The 30-character title limit and the 4,000-character description limit come from App Store Connect, and 10 is the screenshot maximum per device size. Everything else is a judgement call: under 5 iPhone screenshots, under 1,000 description characters, no update in 90 days, or release notes that say only "Bug fixes". Change them to match your category.

Exit codes. The script exits 0 when it found no warnings, 1 when it did, 2 on bad usage and 3 when the API call failed. That makes it easy to run in CI or cron and only shout when something changes.

Running it

I don't own a habit tracker, so for the example I pretend Habitify is mine and compare it with Streaks and Atoms, in the US and UK storefronts:

php audit.php --country=us,gb --json=audit.json 1111447047 963034692 6474421906

Here is the US half of the output:

== Storefront: US ==
Title            Habitify: Habit Tracker            Streaks                            Atoms - from Atomic Habits       
Title chars      23/30 (23 bytes)                   7/30 (7 bytes)                     26/30 (26 bytes)                 
Subtitle         not in API                         not in API                         not in API                       
Description      2997/4000 chars                    3832/4000 chars                    2293/4000 chars                  
First line       Build better habits. Build a be…   STREAKS. The habit tracker that…   Introducing Atoms – The Officia… 
iPhone shots     7/10                               10/10                              7/10                             
iPad shots       3/10                               9/10                               n/a (iPhone-only)                
Languages        40                                 28                               ! 1                                
Version          51.1.0 (5d ago)                    11.5.3 (1d ago)                  ! 3.5.0 (259d ago)                 
Release notes    1133 chars                         407 chars                        ! 26 chars                         
Rating           4.59 (7,160)                       4.81 (27,354)                      4.83 (10,767)                    
Age rating       4+                                 4+                                 4+                               
Price            Free                               $5.99                              Free

And the end of the run:

6 warning(s). '!' marks a check worth a look.

The six warnings were all Atoms, three per storefront: one language (EN), no update in 259 days, and release notes that read, in full, "Bug fixes and enhancements". That doesn't make it a bad app: it has a 4.83 average from over 10,000 US ratings. It does mean a rival could win on freshness and localization.

For "my" app, the table shows things worth asking about: 7 of 10 iPhone slots and only 3 iPad screenshots, while Streaks fills nearly all of both. Streaks uses only 7 of its 30 title characters, a brand-first name that leaves keyword space unused.

The --json file keeps the same rows plus a checked_at timestamp, so you can diff two runs.

The walls you'll hit

1. The API doesn't return the subtitle, keywords or promotional text. This is the big one for an "ASO audit". The subtitle and the 100-character keyword field are two of the three text fields that Apple indexes for search, and the Lookup API has neither. I checked the full key list of the response, and they aren't there. Promotional text is missing too. That's why the table prints not in API instead of pretending. For your own app, read those fields from App Store Connect. For rivals, you can see the subtitle on the store page, but you'll never see their keyword field anywhere.

2. Storefronts really differ. Habitify's description was 2,997 characters in the US and 3,823 in the UK, with a different second sentence. Ratings are per storefront too: Streaks had 27,354 ratings in the US and 4,236 in the UK. Prices come back in local currency ($5.99 vs £5.99). Audit each market you care about separately, and never add up ratings across storefronts and call the total "global". An id that isn't sold in a storefront just disappears from the results with no error. The script warns about it on stderr instead of failing silently.

3. Characters are not bytes. Apple's 30-character limit counts characters. PHP's strlen counts bytes. "Lose It! – Calorie Counter" came back as 26 characters but 28 bytes, because the en dash is three bytes in UTF-8. With strlen, a title in German, Japanese or with a single emoji can look over the limit when it isn't. Use mb_strlen, mb_strimwidth and mb_str_pad everywhere you measure or trim listing text.

4. supportedDevices lies about iPad. My first version flagged Fabulous for having zero iPad screenshots, because its supportedDevices list includes dozens of iPad models. But iPhone-only apps run on iPad too, so that list includes iPads for almost everything. The reliable signal is features containing iosUniversal. Streaks and Habitify have it; Fabulous, Strava and Atoms don't.

5. Responses are cached. The response I got carried cache-control: max-age=38287, which is about ten and a half hours, and it was served through a CDN. If you just shipped a new description, the API may show the old one for hours. Don't use this tool to confirm that a release went live a minute ago, and record checked_at with every run so you know what you were looking at.

6. Rate limits and terms. Apple doesn't publish firm limits for the Lookup API. The related Search API documentation has long suggested about 20 calls per minute, and people do see 403 responses when they go faster. The script batches ids into one call per storefront, pauses between storefronts, sends a clear user agent, and retries 403, 429 and network errors with back-off. It does not retry a 400, which is what you get for a bad country code like xx. Scraping the web store page for the subtitle is tempting, but that page isn't an API, it changes without notice, and automated scraping can break Apple's terms.

Where PeekPanda saves time

This script is good for one job: a quick, repeatable check of a listing as it is today. It can't tell you what happens around the listing. That includes which paid ads a rival runs and for how long, which searches they show up in, or what organic content is driving their installs.

That's the part I use PeekPanda* for. Every iOS app gets a case file, and its Listing & about tab shows the current store description, monetization facts, screenshots and the date of the store observation behind them. The other tabs hold dated paid-ad observations, observed search positions with popularity and difficulty, matched organic content, and download and revenue estimates, labelled as estimates. It doesn't keep listing history, so if you want to see how a listing changed over time, save this script's JSON output on a schedule.

Wrap-up

One PHP file and Apple's Lookup API give you a side-by-side listing audit in seconds, with no key.
Count characters with mb_* functions, audit per storefront, and use iosUniversal for iPad.
Be honest about the gaps: no subtitle, no keyword field, and cached data.

Run it on your own app first. The warnings are usually things you already knew and kept putting off.

*I build it.

Competitor Monitoring on GitHub Actions in Python: Scheduled App Store Snapshots Into a Repo, and the Walls You'll Hit (2026)

Fekri — Mon, 26 Oct 2026 08:19:19 +0000

When a competitor ships a new version, rewrites their description, or swaps their screenshots, you usually find out weeks later by accident. You can fix that without a server, a database, or a scraper. A scheduled GitHub Actions workflow can pull public App Store metadata once a day, commit it to a repo, and open an issue when something you care about changes.

Git becomes the database. git log -p snapshots/us/297368629.json is the full history of one app's listing, and the diff view on GitHub shows exactly what changed.

This post builds that in about 100 lines of Python with no dependencies, plus one workflow file. I ran the script on Python 3.13 against the live API while writing this, tested the commit logic in a local repo, and checked the workflow with actionlint.

The data source

Apple's public Lookup API takes one or more App Store ids and returns the listing as JSON. No key, no account:

https://itunes.apple.com/lookup?id=297368629,6480417616&country=us&entity=software

The id is the number in an app's store URL (apps.apple.com/us/app/.../id297368629). Pass several ids, comma separated, and you get them all back in one request, which matters later. country picks the storefront, and listings differ per storefront, so treat each one separately.

Configuration

A small apps.json holds what to watch. I'm using three calorie-tracking apps in two storefronts as the example:

{
  "countries": ["us", "gb"],
  "apps": [341232718, 297368629, 6480417616]
}

The script

The script fetches every app per storefront in a single call, keeps the fields worth watching, compares them with yesterday's file, and writes a short report.

#!/usr/bin/env python3
"""Snapshot public App Store metadata for a few apps and report what changed.

Writes one JSON file per app and storefront under snapshots/. Git history
is the database: the workflow commits the folder once a day.
"""
import json
import os
import sys
import time
import urllib.parse
import urllib.request
from pathlib import Path

LOOKUP_URL = "https://itunes.apple.com/lookup"
OUT_DIR = Path("snapshots")

# Fields worth watching. Everything else is noise or changes too often.
WATCHED = [
    "trackName", "version", "currentVersionReleaseDate", "releaseNotes",
    "description", "formattedPrice", "primaryGenreName",
    "averageUserRating", "userRatingCount", "screenshotUrls",
]
# Fields that move almost every day; keep them, but don't alert on them.
QUIET = {"averageUserRating", "userRatingCount"}


def lookup(ids, country, retries=3):
    query = urllib.parse.urlencode(
        {"id": ",".join(map(str, ids)), "country": country, "entity": "software"}
    )
    req = urllib.request.Request(
        f"{LOOKUP_URL}?{query}", headers={"User-Agent": "app-snapshots/1.0"}
    )
    for attempt in range(retries):
        try:
            with urllib.request.urlopen(req, timeout=20) as resp:
                return json.load(resp).get("results", [])
        except Exception as exc:  # 403/429/5xx or a timeout
            wait = 10 * (attempt + 1)
            print(f"[{country}] lookup failed ({exc}), retrying in {wait}s",
                  file=sys.stderr)
            time.sleep(wait)
    raise RuntimeError(f"lookup failed for {country} after {retries} tries")


def normalise(app):
    snap = {k: app.get(k) for k in WATCHED}
    # Drop the host and the size suffix ("/392x696bb.jpg"); keep the asset path.
    snap["screenshotUrls"] = [
        urllib.parse.urlsplit(u).path.rsplit("/", 1)[0]
        for u in app.get("screenshotUrls", [])
    ]
    return snap


def diff(old, new):
    changes = []
    for key in WATCHED:
        if old.get(key) != new.get(key):
            changes.append((key, old.get(key), new.get(key)))
    return changes


def short(value, limit=80):
    text = json.dumps(value, ensure_ascii=False)
    return text if len(text) <= limit else text[: limit - 1] + "â€¦"


def main():
    config = json.loads(Path("apps.json").read_text())
    lines = []
    for country in config["countries"]:
        results = {r["trackId"]: r for r in lookup(config["apps"], country)}
        for app_id in config["apps"]:
            path = OUT_DIR / country / f"{app_id}.json"
            app = results.get(app_id)
            if app is None:
                # Not sold in this storefront, pulled, or a flaky response.
                lines.append(f"- `{country}` {app_id}: missing from lookup (kept old snapshot)")
                continue
            new = normalise(app)
            old = json.loads(path.read_text()) if path.exists() else None
            if old is not None:
                for key, before, after in diff(old, new):
                    if key in QUIET:
                        continue
                    lines.append(f"- `{country}` **{new['trackName']}** `{key}`: "
                                 f"{short(before)} â†’ {short(after)}")
            path.parent.mkdir(parents=True, exist_ok=True)
            path.write_text(json.dumps(new, indent=2, ensure_ascii=False, sort_keys=True) + "\n")
        time.sleep(3)  # be polite between storefronts

    report = "\n".join(lines) if lines else "No watched changes."
    print(report)
    Path("changes.md").write_text(report + "\n")
    # GitHub shows this on the run page; locally the variable is unset.
    if summary := os.environ.get("GITHUB_STEP_SUMMARY"):
        with open(summary, "a") as fh:
            fh.write("## App Store changes\n\n" + report + "\n")


if __name__ == "__main__":
    main()

Two design choices are worth explaining.

Watched vs. quiet fields. Rating count and average rating change nearly every day for any popular app. If you alert on them, you'll get an issue every morning and stop reading them within a week. So they're stored (the history is useful) but not reported. Version, release notes, name, description, price and screenshots are the changes a human actually wants to hear about.

One file per app per storefront. Small, stable, sorted JSON makes Git diffs readable. sort_keys=True and a trailing newline stop meaningless reorder diffs.

Running it twice in a row prints No watched changes.. When I edited a snapshot by hand to fake an old version, the next run reported:

- `us` **Lose It! â€“ Calorie Counter** `version`: "0.0.1" â†’ "18.5.702"

I also faked a ratings change in the same file, and it stayed silent, which is what I wanted.

The workflow

name: app-store-snapshots

on:
  schedule:
    - cron: "17 6 * * *"   # 06:17 UTC, off the top of the hour
  workflow_dispatch: {}

permissions:
  contents: write
  issues: write

concurrency:
  group: snapshots
  cancel-in-progress: false

jobs:
  snapshot:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Take snapshots
        run: python snapshot.py
      - name: Commit if anything changed
        run: |
          git config user.name "snapshot-bot"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add snapshots
          if git diff --cached --quiet; then
            echo "nothing to commit"
          else
            git commit -m "snapshots: $(date -u +%F)"
            git push
          fi
      - name: Open an issue for real changes
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          if ! grep -q "No watched changes" changes.md; then
            gh issue create --title "App Store changes $(date -u +%F)" --body-file changes.md
          fi

Put it at .github/workflows/snapshots.yml, push, and trigger it once by hand from the Actions tab (that's what workflow_dispatch is for) to create the first snapshots.

The walls you'll hit

1. The schedule is best-effort, and it's UTC. Cron in Actions runs in UTC, so plan your "morning" accordingly. GitHub also says scheduled runs can be delayed when load is high, and the top of the hour is the busiest time. That's why the example uses minute 17. Don't build anything that needs to run at an exact minute on a scheduled trigger.

2. Schedules can switch themselves off. In public repos, GitHub disables scheduled workflows after 60 days without repository activity. Don't assume the bot's own daily commits keep it alive forever. Look at the Actions tab now and then, or you'll find a two-month hole in your history.

3. Missing apps fail silently. The Lookup API doesn't return an error for an id it can't find. It just leaves it out. That happens when an app isn't sold in a storefront, was pulled, or you copied the wrong id (I did, on my first run, and the report flagged it). The script reports a missing app and keeps the old snapshot, because deleting the file would make a flaky response look like a removal.

4. Noise will kill the alerts. Ratings were the obvious noise. Screenshots are the sneaky one. The URLs contain a size suffix like /392x696bb.jpg and a CDN host, so the script strips both and keeps the asset path. If you watch the raw URL, a change in how you request images looks like a redesign. Every rule like this is a judgement call, so start strict and loosen it when an alert turns out to be useless.

5. The token can do less than you think. The default GITHUB_TOKEN needs contents: write to push and issues: write to open issues, so declare them explicitly. Also, commits pushed with GITHUB_TOKEN don't trigger other workflows. If you planned a second workflow "on push to snapshots/", it won't fire. Chain steps in the same job instead.

6. Rate limits and terms. Apple doesn't publish firm numbers for these endpoints. The Search API docs have long suggested staying around 20 calls per minute, and you'll see 403s if you hammer it. Batching ids into one lookup per storefront keeps this workflow to a handful of calls a day. Store pages and private App Store endpoints are a different story: they sit behind bot protection, and scraping them can break Apple's terms. Read the terms before you build something commercial on top of this.

What this doesn't see

This workflow is good at one thing: telling you that a competitor's listing changed, with a Git diff as proof. It can't tell you what they're doing around the listing. That includes which paid ads they're running and for how long, which App Store searches they show up in, or which short-form videos are driving installs.

For that part I use PeekPanda*. It keeps a dated case file per iOS app with paid ads, observed search positions, organic content and download and revenue estimates, and you can put competitors on a board so they're tracked for you. It doesn't keep listing history, which is one reason I still run this little workflow next to it.

Wrap-up

One Python file, one workflow, and Git history give you a free daily record of competitor listings.
Batch ids per storefront, store everything, and alert only on fields a human cares about.
Expect late schedules, silent misses and noisy fields, and design for them from day one.

Run it for a month and read the diffs. Release notes alone will tell you a lot about what your competitors are shipping.

*I build it.

Build a small RAG app with Next.js, pgvector, and OpenAI

Fekri — Mon, 19 Oct 2026 20:06:40 +0000

Retrieval-augmented generation does not need a large framework or a separate vector database. This walkthrough builds a compact version with Next.js, Postgres, pgvector, the official OpenAI package, and pg.

The complete starter is here: https://github.com/buildfound/rag-starter

The flow has four parts:

Read Markdown and text files.
Split them into overlapping chunks and embed each chunk.
Retrieve the nearest chunks for a question with cosine distance.
Stream an answer that cites the numbered chunks.

Keep vectors in Postgres

If an application already needs relational data, pgvector keeps documents, metadata, and embeddings together. There is one database to run locally, one transaction model, and ordinary SQL for retrieval and filtering.

The local database runs from the pgvector Postgres 16 image. Its initialization SQL enables the extension and creates two tables:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE documents (
  id BIGSERIAL PRIMARY KEY,
  source TEXT NOT NULL UNIQUE,
  title TEXT NOT NULL
);

CREATE TABLE chunks (
  id BIGSERIAL PRIMARY KEY,
  document_id BIGINT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
  chunk_index INTEGER NOT NULL,
  content TEXT NOT NULL,
  embedding vector(1536) NOT NULL,
  UNIQUE (document_id, chunk_index)
);

CREATE INDEX chunks_embedding_hnsw_idx
  ON chunks USING hnsw (embedding vector_cosine_ops);

The vector size matches text-embedding-3-small with 1,536 dimensions. The HNSW index uses cosine distance, which is also used by the retrieval query.

Chunk near useful boundaries

Embedding an entire long document makes retrieval too coarse: a relevant paragraph can be buried inside unrelated text. Very small chunks lose context. This starter uses a deliberately simple middle ground: up to 1,200 characters, split near a paragraph boundary when possible, with roughly 200 characters repeated into the next chunk.

The core loop looks for a useful split late in the current window:

const target = Math.min(start + maxChars, text.length);
const minimumUsefulSplit = start + Math.floor(maxChars * 0.6);
const paragraphBreak = text.lastIndexOf("\n\n", target);
const wordBreak = text.lastIndexOf(" ", target);

if (paragraphBreak >= minimumUsefulSplit) {
  end = paragraphBreak;
} else if (wordBreak > start) {
  end = wordBreak;
}

After storing that slice, the next window begins around end - overlapChars. Whitespace normalization and progress checks keep the function predictable. It is a pure function, so it can be tested without a database or API key.

The ingestion command recursively finds .md and .txt files:

npm run ingest -- ./docs

It embeds chunks in batches of 100. A file path is the document's unique source. On re-ingestion, the script upserts the document, deletes its previous chunks, and inserts the new set in one transaction. That prevents old and new versions from appearing together in search results.

Retrieve with cosine distance

A question is embedded with the same model and dimensions as the documents. pgvector's <=> operator calculates cosine distance, so similarity is 1 - distance:

SELECT d.source, d.title, c.content,
       1 - (c.embedding <=> $1::vector) AS similarity
  FROM chunks c
  JOIN documents d ON d.id = c.document_id
 ORDER BY c.embedding <=> $1::vector
 LIMIT $2

The vector is a parameter, not interpolated SQL. The limit is also parameterized and bounded in application code.

This starter retrieves five chunks. That number is an application choice: adjust it after looking at the kind and length of your own documents.

Make citations part of the prompt

Each retrieved chunk is formatted with a stable number:

[1] How retrieval works (docs/how-it-works.md)
Documents are split into short, overlapping chunks...

The system instruction is explicit: answer only from the numbered context, treat that context as source material rather than instructions, cite factual claims with [n], and say when the answer is absent. This is small but important. Retrieval gives the model relevant text; the instruction defines how that text should be used.

Model-produced citations are still model output. For higher-assurance uses, add checks that citations exist, point to retrieved chunks, and support the claims beside them.

Stream text and send sources first

The route starts an OpenAI chat completion with stream: true, then converts each text delta to bytes for a standard ReadableStream:

const stream = new ReadableStream<Uint8Array>({
  async start(controller) {
    const encoder = new TextEncoder();
    for await (const event of completion) {
      const text = event.choices[0]?.delta?.content;
      if (text) controller.enqueue(encoder.encode(text));
    }
    controller.close();
  },
});

The answer body stays plain text. Source metadata needs to arrive before it, so the route places a base64-encoded JSON array in the x-sources response header. Each entry contains its number, file path, title, and similarity. The browser decodes the header immediately, reads the body stream, and displays only sources whose [n] markers appear in the answer.

An NDJSON stream could carry metadata in its first line, but the header keeps the answer body usable as plain text and makes the protocol easy to inspect.

Run it locally

Create the environment file, add an OpenAI API key, and run the stack:

docker compose up -d
cp .env.example .env.local
npm install
npm run ingest -- ./docs
npm run dev

The OpenAI clients and database pool are created lazily. As a result, npm run build can compile the application without a live database or API key; those values are required only when ingestion or a chat request runs.

From here, useful extensions include metadata filters, more input formats, authentication, rate limiting, and citation validation. The starter keeps those out of the base so the retrieval path remains easy to read.

Built by BuildFound, a founder-led AI product studio.

Keyword Rank Tracking in Python: iTunes Search API, SQLite and Cron, and the Walls You'll Hit (2026)

Fekri — Mon, 19 Oct 2026 09:23:37 +0000

If you ship an iOS app, sooner or later you want to know one boring thing every morning: where does my app show up when someone searches "calorie tracker"? Paid tools answer that, but the DIY version is small enough to build in an afternoon, and building it teaches you more about how App Store search data behaves than any dashboard will.

This post builds a daily keyword rank tracker in Python with:

Apple's public iTunes Search API (no key, no account),
SQLite for history (one file, nothing to run),
cron to run it every day,
a tiny report that shows what moved since the last run.

Then the useful part: the walls you hit once it runs for real.

All code below was run on Python 3.13 against the live API while writing this. It needs Python 3.10+ and requests.

The data source

The iTunes Search API is one public endpoint:

https://itunes.apple.com/search?term=calorie+tracker&country=us&entity=software&limit=200

entity=software restricts results to iOS apps, country picks the storefront, and limit maxes out at 200. Each result has a trackId (the numeric App Store id, the number in apps.apple.com/.../id341232718), the name, the seller, the rating count and more.

Our "rank" is simply the 1-based index of our app's trackId in that ordered list. Keep that definition in mind, because it comes back in the walls section.

Configuration

A JSON file holds what to track. Here I track two well-known calorie apps across two storefronts:

{
  "countries": ["us", "gb"],
  "apps": [6480417616, 341232718],
  "keywords": ["calorie tracker", "calorie counter", "food diary", "macro tracker"]
}

Track your own app plus two or three direct competitors. A rank on its own tells you very little. A rank next to your rivals' ranks tells you a lot.

The tracker

#!/usr/bin/env python3
"""Daily App Store keyword rank tracker: iTunes Search API + SQLite."""
import json
import random
import sqlite3
import sys
import time
from datetime import datetime, timezone

import requests

DB_PATH = "ranks.db"
SEARCH_URL = "https://itunes.apple.com/search"
MAX_RESULTS = 200          # the API's hard ceiling
MIN_INTERVAL = 3.5         # seconds between calls (~17/min, under Apple's ~20/min guidance)

SCHEMA = """
CREATE TABLE IF NOT EXISTS observations (
    observed_at TEXT NOT NULL,      -- UTC ISO timestamp
    country     TEXT NOT NULL,
    keyword     TEXT NOT NULL,
    app_id      INTEGER NOT NULL,
    position    INTEGER,            -- NULL = not in the top MAX_RESULTS
    result_count INTEGER NOT NULL,
    PRIMARY KEY (observed_at, country, keyword, app_id)
);
"""

_last_call = 0.0


def search(term: str, country: str, session: requests.Session, retries: int = 4) -> list[dict]:
    """Return the ordered result list for one search term, with polite pacing and backoff."""
    global _last_call
    params = {"term": term, "country": country, "entity": "software", "limit": MAX_RESULTS}
    for attempt in range(retries):
        wait = MIN_INTERVAL - (time.monotonic() - _last_call)
        if wait > 0:
            time.sleep(wait)
        _last_call = time.monotonic()
        resp = session.get(SEARCH_URL, params=params, timeout=20)
        if resp.status_code == 200:
            # Apple sometimes serves JSON as text/javascript; parse the body ourselves.
            return json.loads(resp.text).get("results", [])
        if resp.status_code in (403, 429, 500, 502, 503):
            backoff = (2 ** attempt) * 10 + random.uniform(0, 5)
            print(f"  {resp.status_code} for {term!r}, sleeping {backoff:.0f}s", file=sys.stderr)
            time.sleep(backoff)
            continue
        resp.raise_for_status()
    raise RuntimeError(f"giving up on {term!r} after {retries} attempts")


def position_of(app_id: int, results: list[dict]) -> int | None:
    for i, r in enumerate(results, start=1):
        if r.get("trackId") == app_id:
            return i
    return None


def run(config_path: str) -> None:
    cfg = json.load(open(config_path))
    db = sqlite3.connect(DB_PATH)
    db.executescript(SCHEMA)
    observed_at = datetime.now(timezone.utc).replace(microsecond=0).isoformat()

    with requests.Session() as session:
        session.headers["User-Agent"] = "rank-tracker/0.1 (you@example.com)"
        for country in cfg["countries"]:
            for keyword in cfg["keywords"]:
                results = search(keyword, country, session)
                rows = [
                    (observed_at, country, keyword, app_id,
                     position_of(app_id, results), len(results))
                    for app_id in cfg["apps"]
                ]
                db.executemany("INSERT OR REPLACE INTO observations VALUES (?,?,?,?,?,?)", rows)
                db.commit()
                print(f"{country} {keyword!r}: " +
                      ", ".join(f"{a}=#{p}" if p else f"{a}=-" for _, _, _, a, p, _ in rows))
    db.close()


if __name__ == "__main__":
    run(sys.argv[1] if len(sys.argv) > 1 else "keywords.json")

A few choices worth explaining:

One timestamp per run. Every row from a run shares observed_at, so "compare today with yesterday" is a join on a single value, not a fuzzy time window.
NULL means "not found in the top 200", not zero. Storing 0 or 201 would poison every average you compute later.
result_count is stored too. If a search suddenly returns 12 results instead of 200, you want to know the API changed, not that your app dropped.
Commit after every keyword. If run 3 of 40 dies on a network error, the first 2 are still saved.

The report

#!/usr/bin/env python3
"""Compare the two most recent runs and print what moved."""
import sqlite3

QUERY = """
WITH runs AS (
    SELECT DISTINCT observed_at FROM observations ORDER BY observed_at DESC LIMIT 2
),
latest AS (SELECT MAX(observed_at) AS t FROM runs),
previous AS (SELECT MIN(observed_at) AS t FROM runs)
SELECT cur.country, cur.keyword, cur.app_id,
       prev.position AS before, cur.position AS after
FROM observations cur
JOIN latest ON cur.observed_at = latest.t
LEFT JOIN observations prev
       ON prev.observed_at = (SELECT t FROM previous)
      AND prev.country = cur.country
      AND prev.keyword = cur.keyword
      AND prev.app_id = cur.app_id
ORDER BY cur.country, cur.keyword, cur.app_id;
"""


def fmt(p):
    return f"#{p}" if p is not None else "-"


def main():
    db = sqlite3.connect("ranks.db")
    for country, keyword, app_id, before, after in db.execute(QUERY):
        if before == after:
            delta = "="
        elif before is None:
            delta = "NEW"
        elif after is None:
            delta = "LOST"
        else:
            delta = f"{before - after:+d}"   # positive = moved up
        print(f"{country:3} {keyword:28} {app_id:<12} {fmt(before):>5} -> {fmt(after):<5} {delta}")


if __name__ == "__main__":
    main()

Running the tracker twice and then the report gives output like this (trimmed):

us  calorie tracker   341232718     #1 -> #1    =
us  calorie tracker   6480417616    #3 -> #3    =
us  food diary        6480417616  #107 -> #107  =
gb  food diary        6480417616   #55 -> #55   =
gb  macro tracker     6480417616    #8 -> #8    =

Two runs a minute apart are boring, which is the point. Run it daily for two weeks and the +3 / LOST lines start telling a story.

Scheduling it

# every day at 06:17 server time
17 6 * * * cd /opt/rank-tracker && /usr/bin/python3 rank_tracker.py >> tracker.log 2>&1 && /usr/bin/python3 report.py >> report.log

Pick an odd minute. Everyone's cron fires at :00, and you don't need to be part of that crowd. Since timestamps are stored in UTC, moving servers or time zones won't scramble your history.

That's the whole tracker. Now the walls.

Wall 1: The Search API is not the App Store search box

This matters most. The iTunes Search API searches the store catalogue. Nobody promises its ordering matches what a person sees in the App Store app. The real search results page can include a Search Ads slot, editorial modules and possibly per-user differences, and Apple doesn't document how either ranking works.

So treat your numbers as a consistent proxy, not ground truth. Measured the same way every day, the trend is meaningful even if "#3" isn't exactly what your users see. Spot-check a handful of keywords on a real device now and then, and write down when the two disagree.

Wall 2: Rate limits are real and vague

Apple's documentation describes the limit as roughly 20 calls per minute, subject to change. Exceed it and you get 403s. That's why the script spaces calls 3.5 s apart and backs off exponentially with jitter on 403/429/5xx.

The arithmetic matters: 50 keywords Ã— 5 storefronts = 250 calls, which is about 15 minutes at a polite pace. Fine for cron, painful if you planned to call this from a web request. If you need more throughput, more IPs is the wrong answer. Track fewer, better keywords.

Wall 3: The 200-result ceiling

limit stops at 200. If your app sits at #240 for a broad term, the API can't tell you that. You only learn "not in the top 200". For a new app that's most keywords, so start by tracking long-tail phrases where you actually appear. A keyword list full of NULLs is a sign to pick different keywords, not to write a smarter scraper.

Wall 4: Every storefront is a different world

The same phrase ranks differently per country. In the run above, one app sat at #107 for "food diary" in the US and #55 in the UK on the same morning. The country parameter changes the results, and so does the language people search in. Don't average storefronts together. Report them separately, and only track storefronts where you actually have users.

Wall 5: Response quirks

Small things that bite:

Some responses come back as text/javascript, not application/json. Parse the body yourself and don't let a strict client reject it.
Results for the same query can wobble between calls. One observation per keyword per day, stored with its timestamp, is more honest than polling hourly and chasing noise.
Apps get removed, renamed or re-categorised. Always key on trackId, never on the app name.

Wall 6: Terms of service and the scraping temptation

Once the Search API's limits annoy you, scraping apps.apple.com or the private storefront endpoints the App Store app uses will look tempting. Don't build on that. Those endpoints are undocumented, change without notice, sit behind bot protection, and using them may break Apple's terms. Read Apple's terms for the Search API too before you build anything commercial on top of it. A tracker that quietly breaks in month three is worse than one that tracks fewer keywords honestly.

Where this stops scaling

The script answers "where do I rank for the words I already chose?" It can't answer the more useful question: which words should I be tracking at all? You can only check keywords you thought to type, so the competitor ranking well for a phrase you never considered stays invisible.

That keyword discovery step is where I stopped writing scripts. I use PeekPanda*, which shows the App Store searches an iOS app has been observed in, with the date each position was seen, plus a keyword gap view comparing your app with a rival. I still keep this little tracker running, because a cron job and a SQLite file you fully understand make a good sanity check against any tool.

Wrap-up

About 120 lines of Python gives you a daily, versioned history of App Store keyword positions.
Store NULL for "not found", one timestamp per run, and key everything on trackId.
Treat positions as a proxy, respect the rate limit, keep storefronts separate, and leave private endpoints alone.

If you run this for a month, the most interesting thing you'll find probably won't be your own rank. It'll be watching a competitor slowly climb a keyword you'd ignored.

*I build it.