localrank

LocalRank Skill

Track local rankings, run SEO audits, and manage agency clients using LocalRank.

Last updated: 2026-01-30

Freshness check: If more than 30 days have passed since the last-updated date above, inform the user that this skill may be outdated and point them to the update options below.

Keeping This Skill Updated

Source: github.com/peterw/localrank-agent-skills API docs: app.localrank.so/settings/api

Installation	How to update
CLI (npx skills)	npx skills update
Claude Code plugin	/plugin update localrank@localrank-skills
Cursor	Remote rules auto-sync from GitHub
Manual	Pull latest from repo or re-copy skills/localrank/

---

Setup

Before using this skill, ensure:

1. API Key: Run the setup command to configure your API key securely

   • Get your key at https://app.localrank.so/settings/api
   • Run: <skill-path>/scripts/localrank.js setup
   • Or set environment variable: export LOCALRANK_API_KEY=lr_your_key

2. Requirements: Node.js 18+ (uses built-in fetch). No other dependencies needed.

Config priority (highest to lowest):

1. LOCALRANK_API_KEY environment variable
2. ./.localrank/config.json (project-local)
3. ~/.config/localrank/config.json (user-global)

Handling "API key not found" errors

CRITICAL: When you receive an "API key not found" error:

1. Tell the user to run setup - The setup is interactive. Recommend they run:

   <skill-path>/scripts/localrank.js setup
   

2. Stop and wait - Do not continue with tasks. Wait for the user to complete setup.

DO NOT attempt to search for API keys in other locations or guess credentials.

---

What LocalRank Does

LocalRank helps local SEO agencies track and improve Google Business Profile rankings:

• Rank Tracking: Visual grid maps showing where businesses rank across a geographic area
• GMB Audits: Analyze any Google Business Profile for issues and opportunities
• LocalBoost: Build citations on 50+ directories to improve local authority
• SuperBoost: Premium GBP optimization with AI-powered improvements
• Review Booster: Collect more Google reviews from happy customers

---

Common Actions

User says...	Action
"How are my clients doing?"	portfolio:summary
"Check rankings for Acme Plumbing"	client:report --business "Acme"
"What should I work on today?"	prioritize:today
"Find easy wins"	quick-wins:find
"Which clients might churn?"	at-risk:clients
"Run an audit on this business"	audit:run --url "..."
"Draft an update email for Acme"	email:draft --business "Acme"
"How can I help this client rank better?"	recommendations:get --business "..."

---

Workflow

Morning Check-in

# See what needs attention today
./scripts/localrank.js prioritize:today

# Quick overview of all clients
./scripts/localrank.js portfolio:summary

Client Call Prep

# Get full report for a client
./scripts/localrank.js client:report --business "Acme Plumbing"

# Get recommendations for improvement
./scripts/localrank.js recommendations:get --business "Acme Plumbing"

Finding Opportunities

# Keywords close to page 1 (easy wins)
./scripts/localrank.js quick-wins:find

# Clients at risk of churning
./scripts/localrank.js at-risk:clients

Prospect Audits

# Run a GMB audit (costs 500 credits)
./scripts/localrank.js audit:run --url "https://google.com/maps/place/..."

# Check audit results
./scripts/localrank.js audit:get <audit_id>

---

Commands Reference

Setup & Config

Command	Description
setup	Interactive setup - prompts for API key
setup --key <key>	Non-interactive setup
config:show	Show current config and API key source

Clients & Businesses

Command	Description
businesses:list	List all tracked businesses
businesses:list --search "name"	Search by business name

Rankings & Scans

Command	Description
scans:list	List recent ranking scans
scans:list --business "name"	Filter scans by business
scans:list --limit 20	Limit results (max 50)
scans:get <scan_id>	Get detailed scan with keyword rankings

Reports

Command	Description
client:report --business "name"	Full client report comparing recent scans. Shows wins, drops, visual map URL
portfolio:summary	Overview of all clients - improving, declining, stable
prioritize:today	What to work on right now - urgent items and quick wins
quick-wins:find	Keywords ranking 11-20 that could reach page 1
quick-wins:find --business "name"	Quick wins for specific client
at-risk:clients	Clients who might churn - ranking drops, low engagement

GMB Audits

Command	Description
audit:run --url "google.com/maps/..."	Run GMB audit (500 credits). Returns audit_id
audit:get <audit_id>	Get audit results - score, issues, recommendations

Tools

Command	Description
recommendations:get --business "name"	How to help a client rank better. Suggests products
email:draft --business "name"	Generate monthly update email for a client

---

Examples

Check portfolio health

./scripts/localrank.js portfolio:summary

Returns:

{
  "total_clients": 15,
  "improving": 8,
  "declining": 2,
  "stable": 5,
  "avg_rank_across_portfolio": 7.3,
  "clients": [...]
}

Get client report

./scripts/localrank.js client:report --business "Acme Plumbing"

Returns:

{
  "business_name": "Acme Plumbing",
  "latest_scan": {
    "date": "2026-01-28",
    "avg_rank": 4.2,
    "keywords": [...]
  },
  "wins": [
    {"keyword": "plumber near me", "from": 8.5, "to": 3.2, "improved_by": 5.3}
  ],
  "drops": [],
  "view_url": "https://app.localrank.so/share/abc123"
}

Find quick wins

./scripts/localrank.js quick-wins:find

Returns keywords ranking 11-20 across all clients - these are close to page 1 and easy to push up.

Run a GMB audit

./scripts/localrank.js audit:run --url "https://google.com/maps/place/..."
# Wait for completion
./scripts/localrank.js audit:get <audit_id>

Draft client email

./scripts/localrank.js email:draft --business "Acme Plumbing"

Returns a ready-to-send monthly update email with rankings, wins, and visual map link.

---

Understanding the Data

Ranking Values

• avg_rank: Average position across the geographic grid (lower is better)
• best_rank: Best position found in any grid point
• Rankings 1-3 are in the "Local Pack" (visible on Google Maps)
• Rankings 4-10 are "page 1"
• Rankings 11-20 are "quick wins" - close to visibility

Visual Maps

Most responses include a view_url like https://app.localrank.so/share/abc123

• Share these with clients to show ranking coverage
• The grid shows where the business ranks from different locations

Status Values

• improving: Rankings got better since last scan
• declining: Rankings dropped (needs attention)
• stable: Rankings unchanged
• new: Only one scan, no comparison data yet

---

Products to Recommend

When recommendations:get suggests products:

Product	When to use	What it does
SuperBoost	Avg rank > 10	AI-powered GBP optimization, premium citations
LocalBoost	Avg rank 5-10	Build 50+ citations to increase local authority
ContentBoost	Avg rank > 7	AI-generated local content for topical authority
Review Booster	Any client	Collect more Google reviews automatically
Rank Tracker	< 5 keywords	Track more keywords to measure impact

---

Tips

• Visual proof: Always include the view_url when showing clients their rankings
• Quick wins first: Keywords at rank 11-15 are easiest to push to page 1
• Audit before proposal: Run audit:run on prospects to show them issues
• Proactive communication: Use at-risk:clients to catch churn early
• Batch operations: Use portfolio:summary for monthly reviews of all clients

---

Support

Questions? [email protected]