SEO Rank Tracking

Keyword rank tracking, grid points, competitors, and AI recommendations.

• Readget_ranking_overviewHow this location ranks on Google (Google Maps / local-pack rank tracker) — Local-search Ranking Analytics OVERVIEW for a single location. Requires locationId. Returns: tracked keywords with their current avg grid rank; the available report months; the grid (per-point ranks) for the active/aggregated keyword; grid stats (top3Pct, top10Pct, avgRank); stat cards (best & worst keyword by avg rank, biggest gainer & dropper month-over-month, count of keywords not ranking); and the map center. Optional keywordId (focus one keyword's grid) and month (a specific report month) — omit for the aggregated latest view. Backs the SEO → Ranking Analytics 'Overview' tab.
• Readget_ranking_grid_pointDrill into ONE grid cell of the rank map: the businesses ranked at that point for a keyword (rank, name, rating, review count, category, address, website, and whether it's you). Requires locationId, keywordId (from get_ranking_overview), and the cell's row + col (0-indexed grid coordinates). Optional month (defaults to latest). This is the 'click a grid point' drill-down.
• Readget_ranking_competitorsWho's beating this location on Google (Google Maps ranking) — Competitor DOMINANCE LEADERBOARD for a location's local-search grid. Requires locationId. Returns each competitor (and you, flagged isYou) with: rating, review count, avg grid rank, % of grid points in the top 3 (top3Pct), grid points covered, category, website, a per-keyword top-3 breakdown, and (when resolved) feature & hours comparison vs you. Backs the SEO → Ranking Analytics 'Competitors' tab leaderboard.
• Readget_ranking_competitor_trendsCompetitor rank-trend over time for a location: the average grid rank per month for you and each tracked competitor (lower is better). Requires locationId. Returns months[] and a per-competitor series (name, isYou, monthly avg-rank aligned to months; null = absent that month). Backs the 'Rank trend over time' chart on the Competitors tab.
• Readget_ranking_rollupGoogle ranking across locations — Multi-location Ranking roll-up across a client's (or the whole agency's) locations: per-location avg grid rank, top3Pct, top10Pct, best keyword, and the location's tags. Optional clientId scopes to one client; omit for agency-wide. Optional tags narrows to locations carrying ANY of the given internal tags (from list_location_tags). Aggregated from stored ranking reports.
• Readget_ranking_recommendationsSydekick 'Next Recommendations' for improving a location's local-search ranking (computed on first request, then cached). Requires locationId. Returns generatedAt and a list of recommendations — each with impact (high/medium/low), the Google Business Profile (GBP) field, title, reasoning, expected impact, a todo checklist, and the suggested Synup action. Backs the 'Next Recommendations' tab. Note: first call may take longer if it needs to generate.
• Readget_ranking_ai_insightSydekick Insight for a location's ranking performance (computed on first request, then cached). Requires locationId. Returns generatedAt, keyword/coverage gaps (with priority), geographic weaknesses (zones where you rank poorly + who dominates), anomalies (with severity + likely cause), and a rating insight (review target). Backs the 'Sydekick Insight' tab. Note: first call may take longer if it needs to generate.
• Writeadd_seo_competitorAdd a competitor to track on a location's local-search ranking grid, by business name (resolved to a Google place near the location when possible). Tracking a competitor here also makes it available to the Reviews and AEO modules for the same location (competitors are shared across modules). Re-adding a previously-removed competitor re-activates it. Requires locationId and name.
• Writeremove_seo_competitorStop tracking a competitor. This archives it (soft delete) — historical ranking data already collected for it is retained. Since competitors are shared across modules, this also removes it from Reviews/AEO for the same location. Identify it by its competitorId (from get_ranking_competitors or add_seo_competitor).
• Readget_seo_keyword_suggestionsGet Sydekick-suggested keywords worth tracking for a location's local-search ranking (computed on first request, then cached — pass force to regenerate). This only suggests — it does NOT start tracking them; pass the ones you want to add_seo_keywords. Requires locationId.
• Writeadd_seo_keywordsStart tracking one or more keywords on a location's local-search ranking grid (geo-grid rank tracker). Up to 25 keywords total per location — extras beyond the cap are silently dropped. Re-adding an already-tracked keyword just re-activates it. Requires the location to have latitude/longitude set (throws otherwise). Optionally set gridSize (3, 5, or 7 — default 7) and distanceKm (default 1.5) the first time you configure a location's grid. excluded skips specific grid points from measurement (e.g. a lake, a rival's territory) — pass the (row, col) cells to exclude, 0-indexed from the grid's top-left.
• Writeremove_seo_keywordStop tracking a keyword on a location's ranking grid. PERMANENTLY DELETES its historical reports and every grid-cell rank point ever recorded for it — there is no undo and no archive; re-adding the same keyword later starts its history over from zero. Identify it by its keywordId (from get_ranking_overview's keywords[]).
• Writeupdate_seo_grid_configUpdate a location's rank-grid measurement config: grid size, distance between points, excluded grid points, or whether water points count toward stats (includeWaterPoints — water cells are always scraped either way; this only controls whether they're counted and shown). Pass only the fields you want to change. Config set here takes effect going forward, same as passing gridSize/distanceKm/excluded to add_seo_keywords the first time a location's grid is configured.
• Writegenerate_seo_reportTrigger (re)generation of ranking-grid reports in the background — either for one tracked keyword, every keyword on a location, or a specific past month. This queues the scrape/compute job and returns immediately (generating:true); poll get_ranking_overview afterward to see the result once it lands. Pass keywordId, or locationId (to regenerate every keyword on that location), or both.
• Readdownload_seo_reportBuild the branded, section-configurable SEO ranking report — the same "Download Report" action in the app. Returns rendered HTML, not a binary PDF file: there's no headless-Chrome renderer available server-side, so turning this into an actual PDF (as the app's own UI does, client-side) is on the caller. preset controls the date window (e.g. "lastMonth"; pass from/to instead for a custom range). sections lets you include/exclude report sections by key: coverPage, executiveSummary, performanceSnapshot, agencyActivityLog, gridRankSnapshots, keywordPerformanceTable, monthOverMonthTrend, competitorLandscape, aiRecommendations — omitted keys use the report's own defaults. Distinct from generate_seo_report, which only enqueues a background rank-grid scan and returns no document.
• Writeregenerate_seo_recommendationsForce-regenerate the Sydekick 'Next Recommendations' for a location instead of using the cached version (get_ranking_recommendations reads the cache; use this when the underlying data has clearly changed, e.g. after a big profile update). Requires locationId.
• Writeregenerate_seo_ai_insightForce-regenerate the Sydekick Insight for a location's ranking performance instead of using the cached version (get_ranking_ai_insight reads the cache). Requires locationId.