Rastreamento de ranking SEO

Rastreamento de ranking de palavras-chave, pontos de grade, concorrentes e recomendações de IA.

• 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 — reads what was already generated; it never starts a generation. Requires locationId. Returns generatedAt (null when nothing has been generated yet — then call regenerate_seo_recommendations, which spends credits) 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.
• Readget_ranking_ai_insightSydekick Insight for a location's ranking performance — reads what was already generated; it never starts a generation. Requires locationId. Returns generatedAt (empty when nothing has been generated yet — then call regenerate_seo_ai_insight, which spends credits), 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.
• 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_suggestionsRead the Sydekick-suggested keywords already generated for a location's local-search ranking — it never starts a generation (`generated: false` and an empty list mean none exist yet: call refresh_seo_keyword_suggestions, which spends credits). This only suggests — it does NOT start tracking them; pass the ones you want to add_seo_keywords. Requires locationId.
• Writerefresh_seo_keyword_suggestionsGenerate (or regenerate) the Sydekick keyword suggestions for a location instead of reading the saved ones — this runs an analysis that spends agency credits. Read the result afterwards, or use the returned suggestions directly. 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 distinct keywords per request. The result lists EVERY keyword you sent in `results` with its outcome — added, reactivated (was removed/inactive), already_tracked, duplicate_in_request (same keyword in another casing), empty, or over_request_limit (beyond the 25; send those in another request) — so check it rather than assuming all were added. 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. Its history is KEPT: past reports and grid points stay, no new scans run for it, and it drops out of the overview. Adding the same keyword again with add_seo_keywords reactivates it with that history. Nothing is deleted. 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, (current month only; past months are not regenerated). This queues one scrape/compute job per keyword and returns immediately with queuedCount and the keywordIds queued (generating is false and queuedCount 0 when the location has no tracked keywords); 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.
• Readlist_website_seo_keywordsRead tracked organic-search keywords and latest results for a website, including rank, previous rank, AI overview visibility and check status. Requires website entities enabled and an active agency user with SEO and client access. Never starts rank checks or AI generation. A null rank is unavailable or outside the measured range, not rank zero.
• Readget_client_ranking_ai_insightRead the saved SEO insight across a client's locations, optionally scoped to one location tag. Requires an active agency user with SEO and client access. Never generates an insight or spends credits. generatedAt:null means no saved insight exists for this scope.
• Writeupdate_website_seo_keywordsAdd or reactivate organic-search keywords for a website and queue their checks, or pass refresh:true without keywords to recheck all active keywords. Requires website entities enabled, an active agency user with SEO and client access, and write scope. Checks spend credits when delivered. A capped result means some keywords were not added; warnings mean saved keywords could not be queued. Read list_website_seo_keywords for completion.
• Writeremove_website_seo_keywordStop tracking one organic-search keyword owned by this website. Keeps historical results and clears the pending-check marker. Requires website entities enabled and an active agency user with SEO and client access. A keyword belonging to another website is refused.
• Writeregenerate_client_ranking_ai_insightGenerate a fresh SEO insight across a client's locations, optionally for one tag. Runs AI analysis and spends credits; use get_client_ranking_ai_insight for a saved-only read. Requires an active agency user with SEO and client access. Returns the completed insight when generation succeeds.