ahrefs

用于 SEO 分析的完整 Ahrefs API 集成。涵盖站点浏览器（域名、反向链接、排名）、关键词浏览器（搜索量、难度、SERP 分析）、排名跟踪器（位置监控）、站点审核（技术 SEO）、SERP 概述、批量分析和品牌雷达。用于任何与 SEO 相关的查询，包括关键词研究、反向链接分析、竞争对手情报、技术审核和排名跟踪。

## 概述（中文）

用于 SEO 分析的完整 Ahrefs API 集成。涵盖站点浏览器（域名、反向链接、排名）、关键词浏览器（搜索量、难度、SERP 分析）、排名跟踪器（位置监控）、站点审核（技术 SEO）、SERP 概述、批量分析和品牌雷达。用于任何与 SEO 相关的查询，包括关键词研究、反向链接分析、竞争对手情报、技术审核和排名跟踪。

## 原文

# Ahrefs SEO Analysis

Query and analyze SEO data using the Ahrefs API for backlinks, keywords, rankings, and competitive intelligence.

## Prerequisites

### API Access
You need an Ahrefs subscription with API access:
- **Lite**: Basic metrics, limited filtering
- **Standard**: More endpoints, some filtering
- **Advanced**: Advanced filtering, more data
- **Enterprise**: Full API access, advanced filtering, high rate limits

### Setup

1. **Get your API token** from [Ahrefs Account Settings](https://ahrefs.com/api)

2. **Configure in OpenClaw**:
   Add to `~/.openclaw/workspace/.env`:
   ```bash
   AHREFS_API_TOKEN=your_api_token_here
   AHREFS_API_PLAN=enterprise  # Options: lite, standard, advanced, enterprise
   ```

3. **Verify setup**:
   ```bash
   grep AHREFS ~/.openclaw/workspace/.env
   ```

## Plan-Specific Features

### All Plans
- Domain Rating & Ahrefs Rank
- Basic backlinks stats (total counts)
- Organic keywords count
- Organic traffic estimates
- Top pages by traffic

### Standard & Above
- Organic keywords with positions (all positions)
- Keywords in positions 1-3 (via `org_keywords_1_3` metric)
- Referring domains list (basic)

### Advanced & Enterprise
- **Advanced filtering**: Filter keywords by position (1-10 for first page)
- **Geographic filtering**: Filter backlinks by country/TLD (e.g., `.au` domains)
- **Detailed keyword data**: Access to `best_position`, `sum_traffic`, `volume`
- **Detailed backlink data**: Full backlinks list with filtering
- **Higher rate limits**: Fetch larger datasets (5000+ records)

## Core Capabilities

### Site Explorer (Domain Analysis)
Get comprehensive SEO metrics for any domain:
- Domain Rating (DR) & URL Rating (UR)
- Organic traffic estimates
- Referring domains & backlinks
- Organic keywords & rankings
- Top pages by traffic
- Historical data & trends
- **[Advanced/Enterprise]** Filter by country/TLD
- **[Advanced/Enterprise]** Position-based filtering (first page only)

### Keywords Explorer (Keyword Research)
Discover and analyze keywords:
- Search volume (global & country-specific)
- Keyword difficulty (KD) score
- Cost per click (CPC) estimates
- SERP analysis & features
- Related keywords & questions
- Keyword ideas & suggestions
- Parent topic analysis
- Traffic potential estimates

### Rank Tracker (Position Monitoring)
Track keyword rankings over time:
- Position tracking & visibility
- Competitor rankings comparison
- SERP feature tracking
- Historical position data
- Share of voice metrics
- **Note:** Requires pre-configured projects in Ahrefs

### Site Audit (Technical SEO)
Identify technical SEO issues:
- Crawl data & site health scores
- On-page issues by severity
- Internal link analysis
- Page performance metrics
- Mobile usability issues
- **Note:** Requires pre-configured projects in Ahrefs

### SERP Overview (Search Results)
Analyze search engine results:
- Top 100 organic results for any keyword
- SERP features present
- Domain metrics for ranking pages
- Keyword difficulty breakdown
- Click-through rate estimates

### Batch Analysis (Bulk Processing)
Process multiple targets efficiently:
- Analyze up to 100 domains/URLs per request
- Bulk keyword metrics
- Batch backlink data
- Cost-effective for large datasets

### Brand Radar (Brand Monitoring)
Track brand performance:
- Brand mention metrics
- Share of voice
- Competitor brand comparison
- Sentiment analysis preparation

### Competitor Analysis
Compare domains and identify opportunities:
- Side-by-side domain comparison
- Content gap analysis
- Keyword overlaps & differences
- Backlink gap analysis
- Traffic comparison
- **[Advanced/Enterprise]** Filtered comparisons (first page keywords, local backlinks)

## API Structure

Ahrefs API base URL: `https://api.ahrefs.com/v3/site-explorer/`

### Authentication
All requests require the API token in the header:
```
Authorization: Bearer {AHREFS_API_TOKEN}
```

**Important:** Use `AHREFS_API_TOKEN`, NOT `AHREFS_MCP_TOKEN`.

### Required Parameters
All API calls require:
- `date`: Current date in format `YYYY-MM-DD`
- `target`: Domain (e.g., `example.com`)

### Common Endpoints

For detailed endpoint documentation and parameters, see [references/api-endpoints.md](references/api-endpoints.md).

## API Unit Management

### Understanding API Units
- Each API request consumes units from your monthly allowance
- Cost depends on rows returned (minimum 50 units per request)
- Enterprise plans include units; additional units can be purchased
- Track usage at: https://app.ahrefs.com/account/limits-and-usage/web

### Cost Optimization Tips
1. **Limit rows returned**: Use `limit` parameter to reduce cost
2. **Select specific columns**: Use `select` parameter for only needed fields
3. **Batch requests**: Process multiple targets in one call (up to 100)
4. **Cache results**: Store frequently accessed data locally
5. **Use date ranges**: Limit historical data when not needed

### Rate Limits
- **60 requests per minute** (default)
- HTTP 429 returned if limit exceeded
- Implement exponential backoff for retries

## Usage Examples

### Site Explorer - Get Backlinks & Referring Domains
```bash
DATE=$(date +%Y-%m-%d)
curl -X GET "https://api.ahrefs.com/v3/site-explorer/backlinks-stats?date=$DATE&target=example.com" \
  -H "Authorization: Bearer $AHREFS_API_TOKEN"
```

Returns:
```json
{
  "metrics": {
    "live": 4545,
    "all_time": 25318,
    "live_refdomains": 718,
    "all_time_refdomains": 3272
  }
}
```

### Get Organic Keywords & Traffic
```bash
DATE=$(date +%Y-%m-%d)
curl -X GET "https://api.ahrefs.com/v3/site-explorer/metrics?date=$DATE&target=example.com" \
  -H "Authorization: Bearer $AHREFS_API_TOKEN"
```

Returns:
```json
{
  "metrics": {
    "org_keywords": 6925,
    "org_traffic": 38702,
    "org_keywords_1_3": 1560,
    "org_cost": 2372016
  }
}
```

### Get Domain Rating
```bash
DATE=$(date +%Y-%m-%d)
curl -X GET "https://api.ahrefs.com/v3/site-explorer/domain-rating?date=$DATE&target=example.com" \
  -H "Authorization: Bearer $AHREFS_API_TOKEN"
```

Returns:
```json
{
  "domain_rating": {
    "domain_rating": 43.0,
    "ahrefs_rank": 1189155
  }
}
```

### Get Top Pages
```bash
DATE=$(date +%Y-%m-%d)
curl -X GET "https://api.ahrefs.com/v3/site-explorer/top-pages?date=$DATE&target=example.com&limit=10&select=url,sum_traffic" \
  -H "Authorization: Bearer $AHREFS_API_TOKEN"
```

### Keywords Explorer - Keyword Research
```bash
curl -X GET "https://api.ahrefs.com/v3/keywords-explorer/overview?keyword=seo+tools&country=us" \
  -H "Authorization: Bearer $AHREFS_API_TOKEN"
```

Returns:
```json
{
  "keyword": "seo tools",
  "volume": 14000,
  "keyword_difficulty": 75,
  "cpc": 25.50,
  "serp_features": ["featured_snippet", "people_also_ask"],
  "traffic_potential": 18500
}
```

### Keywords Explorer - Related Keywords
```bash
curl -X GET "https://api.ahrefs.com/v3/keywords-explorer/related-keywords?keyword=seo+tools&country=us&limit=50" \
  -H "Authorization: Bearer $AHREFS_API_TOKEN"
```

### SERP Overview - Analyze Search Results
```bash
curl -X GET "https://api.ahrefs.com/v3/serp-overview?keyword=seo+tools&country=us" \
  -H "Authorization: Bearer $AHREFS_API_TOKEN"
```

Returns top 100 organic results with domain metrics.

### Rank Tracker - Get Project Rankings
**Note:** Requires pre-configured project in Ahrefs web interface.

```bash
curl -X GET "https://api.ahrefs.com/v3/rank-tracker/project?project_id=12345" \
  -H "Authorization: Bearer $AHREFS_API_TOKEN"
```

### Site Audit - Get Project Issues
**Note:** Requires pre-configured project in Ahrefs web interface.

```bash
curl -X GET "https://api.ahrefs.com/v3/site-audit/project?project_id=12345" \
  -H "Authorization: Bearer $AHREFS_API_TOKEN"
```

### Batch Analysis - Multiple Domains
```bash
curl -X POST "https://api.ahrefs.com/v3/site-explo