Official lightweight Python client for the Serpmax.ru website technical audit API.
Run audits, fetch results, and manage websites with a single line of code β no heavy frameworks, just the standard requests library.
β οΈ Availability notice: Serpmax is currently available for Russian users only. Payments are processed in RUB via Russian payment systems. API access is available on paid plans. π English version of the website: serpmax.ru/en
π·πΊ ΠΠΎΠΊΡΠΌΠ΅Π½ΡΠ°ΡΠΈΡ Π½Π° ΡΡΡΡΠΊΠΎΠΌ
- Python 3.10+
requests2.28+
pip install requests
Copy serpmax_client.py into your project folder.
from serpmax_client import SerpmaxAPI client = SerpmaxAPI(api_key="YOUR_API_KEY") # Run an audit audit = client.create_audit(url="https://example.com") data = audit["data"] print(f"Score: {data['score']}/100") print(f"TTFB: {data['ttfb']} ms") print(f"HTTPS: {data['is_https']}") print(f"SSL OK: {data['is_ssl_valid']}") print(f"Issues: major={data['major_issues']} moderate={data['moderate_issues']} minor={data['minor_issues']}")
Get your API key at: https://serpmax.ru/en/account-api
| Method | Description |
|---|---|
get_user() |
Profile, plan details and limits |
| Method | Description |
|---|---|
list_websites(page, **filters) |
List all websites with pagination |
get_website(website_id) |
Get a single website by ID |
update_website(website_id, **fields) |
Update website settings |
delete_website(website_id) |
Delete a website and all its audits |
| Method | Description |
|---|---|
create_audit(url, audit_type, **options) |
Run a new audit |
list_audits(page, **filters) |
List audits with filtering |
get_audit(audit_id) |
Get full audit report |
update_audit(audit_id, **fields) |
Update audit settings |
delete_audit(audit_id) |
Delete an audit |
| Method | Description |
|---|---|
list_domains(page) |
List custom domains |
get_domain(domain_id) |
Get a single domain by ID |
create_domain(host, scheme, **options) |
Add a custom domain |
delete_domain(domain_id) |
Delete a domain |
user = client.get_user() print(user["data"]["email"]) print(user["data"]["plan_id"])
websites = client.list_websites() websites = client.list_websites(host="example.com") for site in websites["data"]: print(f"{site['host']} score={site['score']} issues={site['total_issues']}")
# Single URL (default) audit = client.create_audit(url="https://example.com") # With auto-refresh every 24 hours audit = client.create_audit( url="https://example.com", audit_check_interval=86400, ) # Bulk β multiple URLs at once audit = client.create_audit( url="https://example.com", audit_type="bulk", urls="https://example.com/page1\nhttps://example.com/page2", ) # Sitemap audit = client.create_audit( url="https://example.com", audit_type="sitemap", urls="https://example.com/sitemap.xml", )
result = client.get_audit(audit_id=1234) data = result["data"] print(f"URL: {data['url']}") print(f"Score: {data['score']}/100") print(f"TTFB: {data['ttfb']} ms") print(f"Response time: {data['response_time']} ms") print(f"Page size: {data['page_size']} KB") print(f"HTTP requests: {data['http_requests']}") print(f"HTTPS: {data['is_https']}") print(f"SSL valid: {data['is_ssl_valid']}") print(f"HTTP/2: {data['http_protocol'] == 2}") print(f"Queued: {data['is_queued']}")
If
is_queued: trueβ the audit is in the processing queue. Retry the request in a few seconds.
audits = client.list_audits(website_id=42) audits = client.list_audits(host="example.com", page=2) print(f"Total: {audits['meta']['total_results']}") for a in audits["data"]: print(f" #{a['id']} {a['url']} score={a['score']}")
All errors are raised as SerpmaxAPIError with a status_code attribute.
from serpmax_client import SerpmaxAPI, SerpmaxAPIError client = SerpmaxAPI(api_key="YOUR_API_KEY") try: audit = client.create_audit(url="https://example.com") except SerpmaxAPIError as e: print(f"Error {e.status_code}: {e}")
| Code | Reason |
|---|---|
401 |
Invalid or missing API key |
403 |
Your plan does not include API access |
429 |
Rate limit exceeded (60 req/min) |
None |
Server unreachable or connection timeout |
Validation errors on client creation are raised as ValueError:
SerpmaxAPI(api_key="") # ValueError: api_key must not be empty. SerpmaxAPI(api_key="Π½Π΅-ascii") # ValueError: api_key contains invalid characters.
Never hardcode your API key. Use environment variables:
import os from serpmax_client import SerpmaxAPI client = SerpmaxAPI(api_key=os.environ["SERPMAX_API_KEY"])
# Linux / macOS export SERPMAX_API_KEY="your_key" # Windows (PowerShell) $env:SERPMAX_API_KEY = "your_key"
- 60 requests per minute per API key
- Exceeding the limit returns
429, the SDK raisesSerpmaxAPIErrorwith code429 - Monthly audit limits depend on your plan β see pricing
.
βββ serpmax_client.py # SDK β import this into your project
βββ example.py # Full usage example
βββ requirements.txt
βββ README.md
MIT