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 rankparseSee 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.
Link graph
| Method | Endpoint | Credits |
|---|---|---|
backlinks(domain, *, limit=100, offset=0, sort="importance", from_domain=None, link_type=None) | GET /v1/backlinks | 2 |
referring_domains(domain, *, limit=100, offset=0) | GET /v1/referring-domains | 2 |
outbound_links(domain, *, limit=100) | GET /v1/outbound-links | 2 |
anchor_text(domain, *, limit=100) | GET /v1/anchor-text | 2 |
top_pages(domain, *, limit=100) | GET /v1/top-pages | 2 |
domain_authority(domain) | GET /v1/domain-authority | 1 |
domain_rank(domain) | GET /v1/domain-rank | 2 |
site_explorer(domain, *, limit=100) | GET /v1/site-explorer | 10 |
batch(domains) | POST /v1/batch | 2 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
| Method | Endpoint | Credits |
|---|---|---|
domain_overlap(domains, *, limit=100) | GET /v1/domain-overlap | 5 |
link_intersect(domain_a, domain_b, *, limit=100) | GET /v1/link-intersect | 5 |
similar_domains(domain, *, limit=100) | GET /v1/similar-domains | 5 |
competitor_gap(domain, vs, *, limit=50) | GET /v1/competitor-gap | 5 |
link_audit(domain) | GET /v1/link-audit | 8 |
domain_overlap takes a list of 2 to 5 domains and joins it with commas.
Live page analysis
| Method | Endpoint | Credits |
|---|---|---|
page_seo(url) | GET /v1/page-seo | 3 |
page_performance(url, *, strategy="mobile") | GET /v1/page-performance | 3 |
schema_markup(url) | GET /v1/schema-markup | 2 |
site_health(domain) | GET /v1/site-health | 2 |
sitemap(domain) | GET /v1/sitemap | 2 |
tech_stack(domain) | GET /v1/tech-stack | 2 |
crawl_history(domain, *, limit=100, offset=0) | GET /v1/crawl-history | 2 |
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
| Method | Endpoint | Credits |
|---|---|---|
link_velocity(domain) | GET /v1/link-velocity | 0 |
new_links(domain) | GET /v1/new-links | 0 |
lost_links(domain) | GET /v1/lost-links | 0 |
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
| Method | Endpoint | Returns |
|---|---|---|
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/keys | A 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/:id | None |
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 withdomain,successand eithertotalanddata(backlink rows) orerror.- 2 credits per domain that succeeds; failed domains are free. Invalid domains are dropped before the lookup.
- More than 50 valid domains raises
APIErrorwith codetoo_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:
| Exception | Status |
|---|---|
AuthError | 401 |
InsufficientCreditsError | 402 (also spend_cap_reached and plan_limit_reached) |
NotFoundError | 404 |
RateLimitError | 429 (also daily caps such as user_quota_exceeded) |
APIError | Anything 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:
platform-domainsandplatform-trendsscore=trueonbacklinksandreferring-domains, andlimitonsitemap- Websites, rank tracking, Search Console, Google Ads
- Issues, indexing, the AI visibility scan, site audits, project context and IndexNow
- Proposals, agent tasks, client report and outreach
GET /v1/pricing,POST /v1/checkoutand the internal links stub (see above)
httpx is already installed with the SDK:
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