Serpmax Python SDK

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

🇷🇺 Документация на русском

---

Requirements

• Python 3.10+
• requests 2.28+

Installation

pip install requests

Copy serpmax_client.py into your project folder.

---

Quick Start

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 Reference

User

Method	Description
get_user()	Profile, plan details and limits

Websites

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

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

Domains (white-label)

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

---

Usage Examples

Get user profile

user = client.get_user()
print(user["data"]["email"])
print(user["data"]["plan_id"])

List websites

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']}")

Run an audit

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

Get audit result

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.

Filter audits

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']}")

---

Error Handling

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.

---

Security

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"

---

Rate Limits

• 60 requests per minute per API key
• Exceeding the limit returns 429, the SDK raises SerpmaxAPIError with code 429
• Monthly audit limits depend on your plan — see pricing

---

Project Structure

.
├── serpmax_client.py   # SDK — import this into your project
├── example.py          # Full usage example
├── requirements.txt
└── README.md

---

License

MIT