# Ahrefs Python

> Gestiona el uso de la API de Ahrefs en Python con la librería `ahrefs-python`: backlinks, keywords, domain ratings, tráfico orgánico, site audits, rank tracking y brand monitoring.

Fuente: https://skillsagentes.com/skills/openclaudia/openclaudia-skills/ahrefs-python
Markdown: https://skillsagentes.com/skills/openclaudia/openclaudia-skills/ahrefs-python.md

Repositorio: https://github.com/OpenClaudia/openclaudia-skills
Autor: OpenClaudia
Licencia: MIT
Actualizado: hace 5 meses
Coste de contexto: 97 tok instalada, 1.9k tok al activarse, 76.4k tok con todos los archivos del bundle
Bundle: 3 archivos, 298 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add OpenClaudia/openclaudia-skills --skill ahrefs-research --agent claude-code
# Cursor
npx -y skills add OpenClaudia/openclaudia-skills --skill ahrefs-research --agent cursor
# Codex
npx -y skills add OpenClaudia/openclaudia-skills --skill ahrefs-research --agent codex
# Gemini CLI
npx -y skills add OpenClaudia/openclaudia-skills --skill ahrefs-research --agent gemini
# Windsurf
npx -y skills add OpenClaudia/openclaudia-skills --skill ahrefs-research --agent windsurf
# Cline
npx -y skills add OpenClaudia/openclaudia-skills --skill ahrefs-research --agent cline
```

## Qué hace

- Configura y usa el cliente AhrefsClient / AsyncAhrefsClient del SDK ahrefs-python para llamar a la API de Ahrefs con modelos tipados
- Permite buscar entre los 52 métodos de la API mediante search_api_methods o el CLI python3 -m ahrefs.api_search
- Aplica manejo de errores tipado (AuthenticationError, RateLimitError, NotFoundError, APIError, APIConnectionError)
- Construye filtros where con json.dumps y usa select/order_by/limit en endpoints de listado

## Cuándo usarla

- Tareas de SEO o marketing con datos de backlinks, keywords, domain ratings, tráfico orgánico, site audits, rank tracking o brand monitoring
- Necesitas trabajar con AhrefsClient / AsyncAhrefsClient, modelos de request/response tipados o cualquier sección de la API de Ahrefs

## Qué la activa

- "Consulta el domain rating de ahrefs.com con la API de Ahrefs en Python"
- "Obtén las keywords orgánicas de un dominio usando ahrefs-python"
- "Compara el domain rating de dos dominios en paralelo con AsyncAhrefsClient"

## Antes de instalar

- Requiere Python 3.11+, instalar `ahrefs-python` (pip3 install git+https://github.com/ahrefs/ahrefs-python.git) y definir la variable de entorno AHREFS_API_KEY.
- Necesita en el PATH: python3
- Variables de entorno: AHREFS_API_KEY
- makes network requests
- needs API credentials

## Archivos

- SKILL.md — 7 KB
- references/api-methods.md — 288 KB
- references/filter-syntax.md — 3 KB

## SKILL.md

Reproducido tal cual desde OpenClaudia/openclaudia-skills bajo MIT. Esta sección es el documento original y está en inglés.

# Ahrefs Python SDK Skill

## Overview

The Ahrefs API provides programmatic access to Ahrefs SEO data. The official Python SDK (`ahrefs-python`) provides typed request and response models for all endpoints, auto-generated from the OpenAPI spec.

Key capabilities:
- **Site Explorer** - Backlinks, organic keywords, domain rating, traffic, referring domains
- **Keywords Explorer** - Keyword research, volumes, difficulty, related terms
- **Rank Tracker** - SERP monitoring, competitor tracking
- **Site Audit** - Technical SEO issues, page content, page explorer
- **Brand Radar** - AI brand mentions, share of voice, impressions
- **SERP Overview** - Search result analysis
- **Batch Analysis** - Bulk domain/URL metrics via POST

## Installation

```sh
pip3 install git+https://github.com/ahrefs/ahrefs-python.git
```

Requires Python 3.11+. Dependencies: `httpx`, `pydantic`.

## API Method Discovery

The SDK has 52 methods across 7 API sections. The built-in search tool is the fastest way to find the right method — it returns matching method signatures, parameters, and return types directly, so there's no need to scan through a large reference.

**Python** (preferred when already in a Python context):

```python
from ahrefs.search import search_api_methods

# Returns formatted text with method signatures, parameters, and return types
print(search_api_methods("domain rating"))

# Filter by API section and limit results
print(search_api_methods("backlinks", section="site-explorer", limit=3))
```

**CLI** (preferred when exploring from the terminal):

```sh
# Ensure python3 points to the interpreter where ahrefs-python is installed:
#   which python3
#   python3 -c "import ahrefs"
python3 -m ahrefs.api_search "domain rating"
python3 -m ahrefs.api_search "backlinks" --section site-explorer --limit 3
python3 -m ahrefs.api_search "batch" --json
python3 -m ahrefs.api_search --sections  # list all API sections
```

## IMPORTANT RULES

- ALWAYS use the `ahrefs-python` SDK. DO NOT make raw `httpx`/`requests` calls to the Ahrefs API.
- ALWAYS pass dates as strings in `YYYY-MM-DD` format (e.g. `"2025-01-15"`).
- ALWAYS use `select` on list endpoints to request only the columns you need. List endpoints return all columns by default, which wastes API units and increases response size.
- USE context managers (`with` / `async with`) for client lifecycle management.
- NEVER hardcode API keys in source code. Use the `AHREFS_API_KEY` environment variable or your preferred secrets mechanism.
- The client handles retries (429, 5xx, connection errors) automatically. DO NOT implement your own retry logic on top of the SDK.

## Quick Start

```python
import os
from ahrefs import AhrefsClient

with AhrefsClient(api_key=os.environ["AHREFS_API_KEY"]) as client:
    data = client.site_explorer_domain_rating(target="ahrefs.com", date="2025-01-15")
    print(data.domain_rating)  # 91.0
    print(data.ahrefs_rank)    # 3
```

## SDK Patterns

### Client Setup

```python
import os
import ahrefs

with ahrefs.AhrefsClient(
    api_key=os.environ["AHREFS_API_KEY"],  # or any secrets source
    base_url="...",          # override API base URL (default: https://api.ahrefs.com/v3)
    timeout=30.0,            # request timeout in seconds (default: 60)
    max_retries=3,           # retries on transient errors (default: 2)
) as client:
    ...
```

Async client:

```python
import os
from ahrefs import AsyncAhrefsClient

async with AsyncAhrefsClient(api_key=os.environ["AHREFS_API_KEY"]) as client:
    data = await client.site_explorer_domain_rating(target="ahrefs.com", date="2025-01-15")
```

For parallel calls, use `asyncio.gather`:

```python
import asyncio

async with AsyncAhrefsClient(api_key=os.environ["AHREFS_API_KEY"]) as client:
    dr_ahrefs, dr_moz = await asyncio.gather(
        client.site_explorer_domain_rating(target="ahrefs.com", date="2025-01-15"),
        client.site_explorer_domain_rating(target="moz.com", date="2025-01-15"),
    )
```

### Calling Methods

Two calling styles -- both are equivalent:

```python
# Keyword arguments (recommended)
data = client.site_explorer_domain_rating(target="ahrefs.com", date="2025-01-15")

# Request objects (full type safety)
from ahrefs.types import SiteExplorerDomainRatingRequest
request = SiteExplorerDomainRatingRequest(target="ahrefs.com", date="2025-01-15")
data = client.site_explorer_domain_rating(request)
```

Method names follow `{api_section}_{endpoint}`, e.g. `site_explorer_organic_keywords`, `keywords_explorer_overview`.

### Responses

Methods return typed Data objects directly.

**Scalar endpoints** return a single data object (or `None`):

```python
data = client.site_explorer_domain_rating(target="ahrefs.com", date="2025-01-15")
print(data.domain_rating)
```

**List endpoints** return a list of data objects. There is no pagination — set `limit` to the number of results you need. Use `select` to request only the columns you need:

```python
items = client.site_explorer_organic_keywords(
    target="ahrefs.com",
    date="2025-01-15",
    select="keyword,volume,best_position",
    order_by="volume:desc",
    limit=10,
)
for item in items:
    print(item.keyword, item.volume, item.best_position)
```

### Error Handling

```python
import ahrefs

try:
    data = client.site_explorer_domain_rating(target="example.com", date="2025-01-15")
except ahrefs.AuthenticationError:    # 401
    ...
except ahrefs.RateLimitError as e:    # 429 -- e.retry_after has the delay
    ...
except ahrefs.NotFoundError:          # 404
    ...
except ahrefs.APIError as e:          # other 4xx/5xx -- e.status_code, e.response_body
    ...
except ahrefs.APIConnectionError:     # network / timeout
    ...
```

All exceptions inherit from `ahrefs.AhrefsError`.

### Common Parameters

Most list endpoints share these parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `target` | `str` | Domain, URL, or path to analyze |
| `date` | `str` | Date in YYYY-MM-DD format |
| `date_from` / `date_to` | `str` | Date range for history endpoints |
| `country` | `str` | Two-letter country code (ISO 3166-1 alpha-2) |
| `select` | `str` | Comma-separated columns to return |
| `where` | `str` | Filter expression |
| `order_by` | `str` | Column and direction, e.g. `"volume:desc"` |
| `limit` | `int` | Max results to return |

Parameters typed as enums in the API reference (`CountryEnum`, `VolumeModeEnum`, etc.) accept plain strings — pass `country="us"` not `CountryEnum("us")`.

The `where` parameter takes a JSON string. Use `json.dumps()` to build it:

```python
import json
where = json.dumps({"field": "volume", "is": ["gte", 1000]})
items = client.site_explorer_organic_keywords(
    target="ahrefs.com", date="2025-01-15",
    select="keyword,volume", where=where,
)
```

For full filter syntax (boolean combinators, operators, nested fields), see `references/filter-syntax.md`.

## API Methods

Use `search_api_methods("query")` or `python3 -m ahrefs.api_search "query"` to find methods by keyword. Search covers all 52 methods across 7 API sections and returns complete signatures, parameters, and response fields.

## Dónde encaja

- Categoría: [SEO y GEO](https://skillsagentes.com/categorias/seo-geo.md) — Keywords, auditorías on-page, datos estructurados y visibilidad en respuestas de IA.
- Creador: [OpenClaudia](https://skillsagentes.com/creators/openclaudia.md) — 76 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Competitor Traffic Report](https://skillsagentes.com/skills/openclaudia/openclaudia-skills/competitor-traffic-report.md): Genera un informe HTML autocontenible de tráfico competitivo: visitas mensuales (SimilarWeb), tráfico orgánico y Domain Rating (Ahrefs), con gráficos ranked, tendencias y tabla de datos.
- [Brand Dev](https://skillsagentes.com/skills/openclaudia/openclaudia-skills/brand-dev.md): Obtiene datos de marca (nombre, descripción, logos, industria) desde la API de brand.dev y guarda los logos localmente.
- [Gsc Portfolio Audit](https://skillsagentes.com/skills/openclaudia/openclaudia-skills/gsc-portfolio-audit.md): Audita TODAS las propiedades de Google Search Console a la vez: ranking por clics e impresiones con deltas, y diff de keywords por sitio (nuevas, suben, bajan, perdidas, o bien rankeadas sin clics).
- [Wechat Moments](https://skillsagentes.com/skills/openclaudia/openclaudia-skills/wechat-moments.md): Clasifica y resume el feed de WeChat Moments (朋友圈) del usuario para que los eventos reales y la información genuina destaquen sobre la promoción, ponderando según cuánto le escribe el usuario a cada autor.
- [Podcast Edit](https://skillsagentes.com/skills/openclaudia/openclaudia-skills/podcast-edit.md): Edita audio o video de podcast: recorta charla previa/posterior, quita muletillas, corta silencios, mejora el audio y aplica el mismo corte a una versión en video.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)