apple-ads-keyword-research
Read Apple Ads (formerly Apple Search Ads) campaign data and research App Store keywords through the Apple Ads Platform API. Use for campaign, ad group, keyword, or search term performance (spend, taps, installs, CPT, CPI), Apple's keyword and phrase suggestions, relative App Store search popularity by country and genre, impression share and rank, ASO keyword ideas, or deciding which App Store keywords to add, pause, negate, or bid on. Read-only; it never changes campaigns.
- License 许可
- MIT
- 最近更新
- 2026-11-06
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- apple-ads-keyword-research
- description
- Read Apple Ads (formerly Apple Search Ads) campaign data and research App Store keywords through the Apple Ads Platform API. Use for campaign, ad group, keyword, or search term performance (spend, taps, installs, CPT, CPI), Apple's keyword and phrase suggestions, relative App Store search popularity by country and genre, impression share and rank, ASO keyword ideas, or deciding which App Store keywords to add, pause, negate, or bid on. Read-only; it never changes campaigns.
02 资源文件 6
- 参考文档agents/openai.yaml332 B
- 参考文档README.md2.6 KB
- 参考文档references/cli-and-metrics.md12.3 KB
- 参考文档references/setup.md5.4 KB
- 脚本scripts/apple_ads.py45.9 KB
- 脚本tests/test_apple_ads.py31.8 KB
03 SKILL.md 正文
Apple Ads Keyword Research
Use observed Apple Ads data to make keyword and campaign decisions. The script retrieves data; the agent judges intent, relevance, evidence, and priority.
Choose the decision
- Campaign performance: how campaigns, ad groups, keywords, or search terms perform, where spend produces no installs, and which search terms to add as exact keywords or negatives. Use
campaignsandreport. - Keyword research for ads or ASO: what people search for in the App Store and how popular it is. Use
ideas,phrases, andpopularity; addimpression-sharewhen the app already runs ads. None of these need spend history. - Both: keep observed performance separate from popularity-based discovery. A popular term with no performance data is a candidate to test.
Research never authorizes changes. Present keyword additions, negatives, pauses, and bid changes as proposals for the user to apply.
Establish the brief
Identify the app (its Adam ID; apps --owned lists them), the App Store countries or regions, the date range, and the goal: installs at a target CPI or CPT, brand defense, or discovery. Ask when the country is missing. Do not default to the US or the account's home market. Apple Ads targets storefronts, not languages, so note when a storefront has customers searching in more than one language.
Keep markets separate. Suggestion popularity blends every requested country, so request one country per call to rank a market. Popularity and impression share rows are per country; never sum or average them into a combined market.
Get access and choose a command
Run the bundled script by its installed absolute path:
uv run /path/to/apple-ads-keyword-research/scripts/apple_ads.py --help
Read setup.md for first-time API access, missing credentials, or access errors. Credentials come from an external TOML file via --config or from APPLE_ADS_* environment variables. Never ask the user to paste a private key, client secret, or token into chat. Start with doctor to list the ad accounts the credentials can reach, then run doctor --ad-account-id ID to verify one.
Read cli-and-metrics.md for arguments, output fields, limits, and interpretation.
appsandappfind the Adam ID, its storefronts, and its primary genre.campaignslists campaigns with status, countries, budget, and bid strategy. Use it to find campaign IDs.report --level campaigns|adgroups|keywords|searchtermsreturns performance for a date range. Ad group, keyword, and search term reports take exactly one--campaign-id, so loop over campaigns for an account-wide view.--include-emptyadds keywords that had no activity.--granularityadds a time series; omit it for period totals.ideasreturns Apple's keyword suggestions for a promoted app, optionally seeded with--termand limited by--country.phrasesdiscovers search phrases for an app (--adam-id), looks up the popularity of known phrases (--term), or matches part of a phrase (--like).popularityreturns the top search terms for a country and App Store genre with rank and popularity scores, weekly or monthly. Use--termto check specific candidates.impression-shareshows how often the app's ads appeared for each search term, its rank against other advertisers, and the term's 1–5 popularity.- For more than a handful of rows, pass
--output file.json(and--csvif wanted). Stdout then shows a compact TSV summary instead of the full JSON; read the file only for the fields you need.
Every command reads data. The client sends only GET requests and POST requests to /query endpoints, and refuses anything else.
Do the setup and research work you can, then name the exact missing user action if API access blocks live calls. Missing access never justifies invented popularity, spend, or install numbers.
Select and explain
- Apply product relevance first: what does the searcher want, and can this app give it to them? Hold ambiguous terms. Treat competitor brand names as a separate conquesting decision for the user.
- Compare keywords and search terms on tap-through metrics (
tap_installs,tap_install_rate,tap_install_cpi). Thetotal_*metrics add view-through installs that Apple credits to impressions. Say which basis you use, and say when a keyword has too few taps to judge. - Search term reports show what people typed. A search term with good tap-through installs that is not yet an exact keyword is a candidate to add as one; an irrelevant or expensive term without installs is a negative candidate.
search_term_source: AUTOmeans Apple matched the search automatically. Rows without search term text are unattributed searches. - Popularity is relative.
popularity(suggestions, 0–100),search_popularity_1to100,search_popularity_1to5, andrank_in_genreare scores and ranks. Never convert them into monthly searches or compare them with Google volumes. A term missing frompopularityfell below Apple's threshold or outside the top 500 for that country and genre; its demand is unknown. - Impression share shows headroom. Low share on a popular, converting term points to bid, budget, or relevance limits. A share of 0.91–1.0 means above 90%, where a higher bid buys little.
bid_recommendationis Apple's suggestion and says nothing about affordability. When the user gives a target CPI, the break-even CPT is that CPI times the observedtap_install_rate; label it an estimate and show both inputs. - Preserve null versus zero, the date range, the time zone, currency, country, and truncation. Reports default to the account time zone (
ORTZ), search term reports only support it, and popularity and impression share always use UTC. A truncated response is a sample, ordered by the requested sort rather than by priority.
Deliver
Give a short answer backed by the data. For performance, rank keywords or search terms with spend, taps, installs, CPI, and the period. For research, group a shortlist by intent with popularity, rank, country, and the reason for each pick. Separate observations from proposals (add, pause, negate, change a bid), and include exclusions or uncertainties that change the decision.
Link requested JSON and CSV exports and state the ad account, app, countries, period, time zone, currency, retrieval time, and any truncation or missing data. Keep raw exports separate from your judgment. Reuse exports for follow-up questions when their scope and freshness fit: monthly popularity updates on the 5th of each month, weekly popularity every Monday.
04 同仓库更多 Skills
motion-design
Plan, build, and review short motion-design films for SaaS and app marketing: launch videos, product films, promo and social ad clips, app trailers, and landing-page loops of roughly 6–45 seconds. Develops the brief, promise, storyline, rendered key frames, timed beat sheet, and sound plan first, has them critiqued with fresh eyes, and gets sign-off before any animation, because iterating on a plan is far cheaper than iterating on renders. Then builds the film (following the project's motion studio when one exists, otherwise a code-rendered timeline) and reviews cuts with a scored rubric and prioritized fixes. Use whenever the user wants to make, script, storyboard, animate, render, critique, or fix a product video, motion graphics ad, launch clip, or app promo, even if they only say 'make a video for my app' or share a cut for feedback. Not for UI micro-interactions inside the product itself.
mise
Set up, migrate, or maintain a project on the team's mise stack: mise tools and tasks under one shared task-naming convention, deployment environments as mise config environments (mise.<env>.toml), uv for Python, bun for JavaScript and TypeScript, Terraform in terraform/, and optional fnox secrets (Proton Pass locally, environment variables in CI and on deployed hosts). Invoke it to replace a Makefile, justfile, or package scripts, add or rename tasks, add secrets or environments, or bootstrap a repository.
grafana
Set up lean application monitoring in Grafana Cloud for a solo maintainer running several web apps, APIs, mobile backends, or jobs on GCP or AWS. Use when adding metrics or monitoring to an app; sending OpenTelemetry (OTLP) or Prometheus metrics to Grafana Cloud; querying Cloud Run, Lambda, Cloud Monitoring, or CloudWatch metrics from Grafana; building or fixing app and portfolio dashboards; or keeping active series within the free tier. Also covers client-side health signals for mobile and browser apps and whether a first alert is worth adding.
google-keyword-research
Research Google keywords for SEO and paid search using Google Ads planning data (Keyword Planner). Use for keyword ideas, search volume, "how many people search for" questions, CPC and bid estimates, competition, seasonality, or a Search Viability Loop that prices commercial keyword clusters against contribution-based acquisition ceilings and read-only forecasts before proposing a paid test.
frontend-design
Design, implement, and refine polished web interfaces: new screens, components, dashboards, landing pages, and visual redesigns. Use when UI quality, layout, typography, responsive behavior, or interaction polish is part of the task, including requests to make an interface look better. Reuses or establishes a design system and verifies the rendered result. Not for backend-only work or logic changes with no visual impact.
agentic-browsing-auditor
Verify and improve a website, current page, or frontend repository for Lighthouse Agentic Browsing readiness. Use when asked to audit, raise, improve, or debug agentic browsing level, WebMCP readiness, llms.txt discoverability, agent-accessible forms, accessibility-tree quality for agents, or layout stability for AI/browser agents.