Ahrefs Python SDK oskus

Ülevaade

Ahrefs API annab programmilise juurdepääsu Ahrefs SEO andmetele. Ametlik Python SDK (ahrefs-python) pakub tüübitud päringu- ja vastusemudeleid kõigile otspunktidele, automaatselt genereeritud OpenAPI spetsifikatsioonist.

Peamised võimed: - Site Explorer - Tagasilinkid, orgaanilised märksõnad, domain rating, liiklus, viitavad domeenid - Keywords Explorer - Märksõnauuring, mahud, raskus, seotud terminid - Rank Tracker - SERP jälgimine, konkurentide jälgimine - Site Audit - Tehnilised SEO probleemid, lehe sisu, page explorer - Brand Radar - AI brändimainimised, share of voice, impressions - SERP Overview - Otsingutulemuste analüüs - Batch Analysis - Hulgi domeeni/URL mõõdikud POST-iga

Paigaldus

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

Nõuab Python 3.11+. Sõltuvused: httpx, pydantic.

API meetodite avastamine

SDK-l on 52 meetodit 7 API sektsioonis. Sisseehitatud otsingutööriist on kiireim viis õige meetodi leidmiseks — see tagastab sobivad meetodisignatuurid, parameetrid ja tagastustüübid otse, nii et suurt viidet ei pea skaneerima.

Python (eelistatud, kui oled juba Pythoni kontekstis):

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 (eelistatud terminalist uurides):

# 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

OLULISED REEGLID

• Kasuta ALATI ahrefs-python SDK-d. ÄRA tee tooreid httpx/requests kutseid Ahrefs API-le.
• Anna kuupäevad ALATI stringidena YYYY-MM-DD formaadis (nt "2025-01-15").
• Kasuta loendotspunktidel ALATI select, et küsida ainult vajalikke veerge. Loendotspunktid tagastavad vaikimisi kõik veerud, mis raiskab API ühikuid ja suurendab vastuse mahtu.
• Kasuta kontekstihaldureid (with / async with) kliendi elutsükli halduseks.
• ÄRA kunagi hardcode’i API võtmeid lähtekoodi. Kasuta AHREFS_API_KEY keskkonnamuutujat või eelistatud saladuste mehhanismi.
• Klient käsitleb korduskatseid (429, 5xx, ühendusvead) automaatselt. ÄRA rakenda oma korduskatse loogikat SDK peale.

Kiirstart

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 mustrid

Kliendi seadistus

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

Asünkroonne klient:

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

Paralleelsete kutsete jaoks kasuta 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"),
    )

Meetodite kutsumine

Kaks kutsumisstiili — mõlemad on samaväärsed:

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

Meetodinimed järgivad {api_section}_{endpoint}, nt site_explorer_organic_keywords, keywords_explorer_overview.

Vastused

Meetodid tagastavad tüübitud Data objektid otse.

Skaalarotspunktid tagastavad ühe andmeobjekti (või None):

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

Loendotspunktid tagastavad andmeobjektide loendi. Leheküljestamist pole — sea limit vajalike tulemuste arvule. Kasuta select, et küsida ainult vajalikke veerge:

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)

Veakäsitlus

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

Kõik erandid pärinevad ahrefs.AhrefsError’ist.

Levinud parameetrid

Enamik loendotspunkte jagab neid parameetreid:

Parameetrid, mis on API viites enum’idena (CountryEnum, VolumeModeEnum jne), aktsepteerivad lihtsaid stringe — anna country="us", mitte CountryEnum("us").

where parameeter võtab JSON-stringi. Ehita see json.dumps() abil:

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

Täieliku filtrisüntaksi jaoks (boolean kombinaatorid, operaatorid, pesastatud väljad) vt references/filter-syntax.md.

API meetodid

Kasuta search_api_methods("query") või python3 -m ahrefs.api_search "query", et leida meetodeid märksõna järgi. Otsing katab kõik 52 meetodit 7 API sektsioonis ja tagastab täielikud signatuurid, parameetrid ja vastuseväljad.