Skip to Content

Python SDK

The official Python client for the RankParse API, version 0.1.1. Sync and async clients, one dependency (httpx).

rankparse on PyPI (version 0.1.1) wraps the link graph, live page and account endpoints, with a sync client and an async client that share the same methods. It needs Python 3.9 or later and depends only on httpx (0.27 or later). Everything it does not wrap is one httpx call away, with the same key (see Endpoints the SDK does not cover).

Installation

pip install rankparse

See the Python landing page for framework examples.

Quick start

import os
from rankparse import RankParseClient

client = RankParseClient(api_key=os.environ["RANKPARSE_API_KEY"])

result = client.domain_authority("github.com")
print(result["data"]["score"])
print(result["credits_used"], result["credits_remaining"])

Async client

import asyncio
import os
from rankparse import AsyncRankParseClient

async def main():
    async with AsyncRankParseClient(api_key=os.environ["RANKPARSE_API_KEY"]) as client:
        result = await client.domain_authority("github.com")
        print(result["data"]["score"])

asyncio.run(main())

Every method below exists on both clients; on AsyncRankParseClient it is a coroutine. Close a client with client.close() (sync) or await client.aclose() (async), or use it as a context manager as above.

Configuration

from rankparse import RankParseClient

client = RankParseClient(
    api_key="rp_your_key",                    # required, sent as X-API-Key
    base_url="https://api.rankparse.com/v1",  # optional
    timeout=30.0,                             # optional, seconds, default 30
)

The client does not retry on its own; see Rate limiting for a backoff loop. Note that rankparse.__version__ reports "0.1.0" in the 0.1.1 package.

Responses

Each method returns the parsed JSON body as a dict, exactly as documented on the endpoint's page: the envelope (data, credits_used, credits_remaining, plus domain, total and limit where they apply) is unchanged. The exceptions are keys(), which returns the list of keys, and revoke_key(), which returns None.

Methods

Costs are in credits; see Credits for refunds. Arguments after * are keyword-only.

MethodEndpointCredits
backlinks(domain, *, limit=100, offset=0, sort="importance", from_domain=None, link_type=None)GET /v1/backlinks2
referring_domains(domain, *, limit=100, offset=0)GET /v1/referring-domains2
outbound_links(domain, *, limit=100)GET /v1/outbound-links2
anchor_text(domain, *, limit=100)GET /v1/anchor-text2
top_pages(domain, *, limit=100)GET /v1/top-pages2
domain_authority(domain)GET /v1/domain-authority1
domain_rank(domain)GET /v1/domain-rank2
site_explorer(domain, *, limit=100)GET /v1/site-explorer10
batch(domains)POST /v1/batch2 per successful domain

offset is sent but the API ignores it: the link graph endpoints return the top limit rows. The SDK has no argument for score=true; call the endpoint over HTTP for scored rows.

Competitive analysis

MethodEndpointCredits
domain_overlap(domains, *, limit=100)GET /v1/domain-overlap5
link_intersect(domain_a, domain_b, *, limit=100)GET /v1/link-intersect5
similar_domains(domain, *, limit=100)GET /v1/similar-domains5
competitor_gap(domain, vs, *, limit=50)GET /v1/competitor-gap5
link_audit(domain)GET /v1/link-audit8

domain_overlap takes a list of 2 to 5 domains and joins it with commas.

Live page analysis

MethodEndpointCredits
page_seo(url)GET /v1/page-seo3
page_performance(url, *, strategy="mobile")GET /v1/page-performance3
schema_markup(url)GET /v1/schema-markup2
site_health(domain)GET /v1/site-health2
sitemap(domain)GET /v1/sitemap2
tech_stack(domain)GET /v1/tech-stack2
crawl_history(domain, *, limit=100, offset=0)GET /v1/crawl-history2

crawl_history sends limit and offset, which the API ignores. sitemap takes no limit, so it always returns the default 100 URLs.

Not yet available

MethodEndpointCredits
link_velocity(domain)GET /v1/link-velocity0
new_links(domain)GET /v1/new-links0
lost_links(domain)GET /v1/lost-links0

They return status: "not_yet_available". internal_links(url, ...) also exists, but it sends url where the API expects domain, so in 0.1.1 it raises APIError with code invalid_domain.

Account

MethodEndpointReturns
credits()GET /v1/credits{"credits", "plan_credits", "purchased_credits", "plan_credits_expire_at"}, no envelope
me()GET /v1/me{"id", "email", "credits", "created_at"} (credits is None for a role that cannot view credits)
keys()GET /v1/keysA list of {"id", "name", "last_four", "created_at"}
create_key(name="Default")POST /v1/keys{"id", "key", "name", "created_at"}. The raw key is shown once.
revoke_key(key_id)DELETE /v1/keys/:idNone
usage(*, limit=50, offset=0)GET /v1/usage{"usage", "total"}. limit max 200.

These are free. checkout(pack_id) is also in 0.1.1, but it sends pack_id where POST /v1/checkout expects credits, so it raises APIError with code invalid_credits. Buy credits in the dashboard instead.

Batch lookup

batch(domains) runs a backlinks lookup for up to 50 domains in one request:

result = client.batch(["stripe.com", "github.com", "vercel.com"])

for item in result["data"]:
    if item["success"]:
        print(item["domain"], item["total"], "backlinks")
    else:
        print(item["domain"], "failed:", item["error"])

print(result["credits_used"], result["credits_remaining"])
  • result["data"] holds one entry per valid input domain, in order, each with domain, success and either total and data (backlink rows) or error.
  • 2 credits per domain that succeeds; failed domains are free. Invalid domains are dropped before the lookup.
  • More than 50 valid domains raises APIError with code too_many_domains. A batch counts as one request against the rate limit of 60 requests per minute per key (Rate limiting).

Error handling

Any non-2xx response raises. The class depends on the status:

ExceptionStatus
AuthError401
InsufficientCreditsError402 (also spend_cap_reached and plan_limit_reached)
NotFoundError404
RateLimitError429 (also daily caps such as user_quota_exceeded)
APIErrorAnything else

All of them subclass RankParseError and carry status and code. code is the API's error code, or unknown_error when the body has none (the live page endpoints, for example). A timeout or connection problem raises the httpx exception, not a RankParseError.

from rankparse import RankParseError, RateLimitError, InsufficientCreditsError

try:
    result = client.backlinks("stripe.com")
except RateLimitError as err:
    if err.code != "rate_limited":
        raise  # a daily cap: wait for 00:00 UTC
    # back off and retry
except InsufficientCreditsError as err:
    print("Payment required:", err.code)  # insufficient_credits, spend_cap_reached, plan_limit_reached
except RankParseError as err:
    print(err.status, err.code, err)

The full list of codes is in Errors.

Endpoints the SDK does not cover

0.1.1 has no methods for these. Call them over HTTP with the same key:

httpx is already installed with the SDK:

Plain HTTP call
import os
import httpx

BASE = "https://api.rankparse.com/v1"
headers = {"X-API-Key": os.environ["RANKPARSE_API_KEY"]}

# GET with query parameters
resp = httpx.get(
    f"{BASE}/platform-domains",
    params={"platform": "shopify", "limit": 25},
    headers=headers,
    timeout=60,
)
if resp.is_error:
    err = resp.json()  # {"error": ..., "code": ..., "message": ...}
    raise RuntimeError(f"{resp.status_code} {err.get('code')}")
body = resp.json()
print(len(body["data"]), body["credits_used"], body["credits_remaining"])

# POST with a JSON body
httpx.post(
    f"{BASE}/indexnow",
    json={"urls": ["https://example.com/new-page"]},
    headers=headers,
    timeout=60,
)

For async code, use httpx.AsyncClient the same way.

Pandas enrichment

import os
import pandas as pd
from rankparse import RankParseClient

client = RankParseClient(api_key=os.environ["RANKPARSE_API_KEY"])

df = pd.read_csv("domains.csv")
df["score"] = df["domain"].apply(
    lambda d: client.domain_authority(d)["data"]["score"]
)
df.sort_values("score", ascending=False).to_csv("enriched.csv")

Each lookup costs 1 credit and counts against the 60 per minute rate limit, so pace large files or use batch for backlink counts.

Source and issues

GitHub: abhibavishi/rankparse-python

On this page