ahrefs-python

Ahrefs Python SDK 技能

概述

Ahrefs API 提供以编程方式访问 Ahrefs SEO 数据的能力。官方 Python SDK（ahrefs-python）为所有端点提供类型化的请求和响应模型，这些模型由 OpenAPI 规范自动生成。

主要功能：

• Site Explorer - 反向链接、自然关键词、域名评级、流量、引荐域名
• Keywords Explorer - 关键词研究、搜索量、难度、相关词
• Rank Tracker - SERP 监控、竞争对手追踪
• Site Audit - 技术 SEO 问题、页面内容、页面浏览器
• Brand Radar - AI 品牌提及、声量份额、展示次数
• SERP Overview - 搜索结果分析
• Batch Analysis - 通过 POST 批量获取域名/URL 指标

安装

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

需要 Python 3.11+。依赖项：httpx、pydantic。

API 方法发现

SDK 在 7 个 API 分区中包含 52 个方法。内置搜索工具是查找合适方法的最快方式——它会直接返回匹配方法的签名、参数和返回类型，因此无需逐一查阅大型参考文档。

Python（已在 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（从终端探索时优先使用）：

# 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

重要规则

• 始终使用 ahrefs-python SDK。不要直接调用 Ahrefs API 的 httpx/requests 接口。
• 始终以 YYYY-MM-DD 格式的字符串传递日期（例如 "2025-01-15"）。
• 始终在列表端点上使用 select，仅请求所需的列。列表端点默认会返回所有列，这会浪费 API 单位并增加响应大小。
• 使用上下文管理器（with / async with）管理客户端生命周期。
• 切勿在源代码中硬编码 API 密钥。请使用 AHREFS_API_KEY 环境变量或你首选的密钥管理机制。
• 客户端会自动处理重试（429、5xx、连接错误）。不要在 SDK 之上自行实现重试逻辑。

快速入门

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 模式

客户端设置

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:
    ...

异步客户端：

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")

并行调用时，使用 asyncio.gather：

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"),
    )

调用方法

两种调用方式——效果相同：

# 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)

方法名称遵循 {api_section}_{endpoint} 格式，例如 site_explorer_organic_keywords、keywords_explorer_overview。

响应

方法会直接返回类型化的 Data 对象。

标量端点返回单个数据对象（或 None）：

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

列表端点返回数据对象列表。无需分页——将 limit 设为所需结果数量。使用 select 仅请求所需的列：

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)

错误处理

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
    ...

所有异常都继承自 ahrefs.AhrefsError。

常用参数

大多数列表端点共用以下参数：

参数	类型	说明
target	str	要分析的域名、URL 或路径
date	str	YYYY-MM-DD 格式的日期
date_from / date_to	str	历史记录端点的日期范围
country	str	两字母国家代码（ISO 3166-1 alpha-2）
select	str	要返回的列，以逗号分隔
where	str	筛选表达式
order_by	str	列名和排序方向，例如 "volume:desc"
limit	int	要返回的最大结果数

API 参考中声明为枚举类型的参数（CountryEnum、VolumeModeEnum 等）可接受普通字符串——传入 country="us"，而不是 CountryEnum("us")。

where 参数接受 JSON 字符串。使用 json.dumps() 来构造：

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,
)

完整筛选语法（布尔组合器、运算符、嵌套字段）请参阅 references/filter-syntax.md。

API 方法

使用 search_api_methods("query") 或 python3 -m ahrefs.api_search "query" 按关键词查找方法。搜索涵盖 7 个 API 分区中的全部 52 个方法，并返回完整的签名、参数和响应字段。