Serpmax Python SDK

Официальный легковесный Python-клиент для API сервиса технического аудита сайтов serpmax.ru.

Позволяет запускать аудиты, получать результаты и управлять сайтами одной строчкой кода — без тяжёлых фреймворков, только стандартная библиотека requests.

🇬🇧 English documentation

Требования

Python 3.10+
requests 2.28+

Установка

pip install requests

Скопируйте файл serpmax_client.py в папку вашего проекта.

Быстрый старт

from serpmax_client import SerpmaxAPI

client = SerpmaxAPI(api_key="ВАШ_API_КЛЮЧ")

# Запустить аудит
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']}")

Получить API-ключ можно в личном кабинете: https://serpmax.ru/account-api

Справочник методов

Пользователь

Метод	Описание
`get_user()`	Профиль, тарифный план и лимиты

Сайты

Метод	Описание
`list_websites(page, **filters)`	Список всех сайтов с пагинацией
`get_website(website_id)`	Один сайт по ID
`update_website(website_id, **fields)`	Обновить настройки сайта
`delete_website(website_id)`	Удалить сайт и все его аудиты

Аудиты

Метод	Описание
`create_audit(url, audit_type, **options)`	Запустить новый аудит
`list_audits(page, **filters)`	Список аудитов с фильтрацией
`get_audit(audit_id)`	Полный отчёт по аудиту
`update_audit(audit_id, **fields)`	Обновить настройки аудита
`delete_audit(audit_id)`	Удалить аудит

Домены (white-label)

Метод	Описание
`list_domains(page)`	Список кастомных доменов
`get_domain(domain_id)`	Один домен по ID
`create_domain(host, scheme, **options)`	Добавить домен
`delete_domain(domain_id)`	Удалить домен

Примеры использования

Получить профиль пользователя

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

Запустить аудит

# Одиночный URL (по умолчанию)
audit = client.create_audit(url="https://example.com")

# С автообновлением каждые 24 часа
audit = client.create_audit(
    url="https://example.com",
    audit_check_interval=86400,
)

# Bulk — несколько URL сразу
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']}")

Если is_queued: true — аудит поставлен в очередь. Повторите запрос через несколько секунд.

Обработка ошибок

from serpmax_client import SerpmaxAPI, SerpmaxAPIError

client = SerpmaxAPI(api_key="ВАШ_API_КЛЮЧ")

try:
    audit = client.create_audit(url="https://example.com")
except SerpmaxAPIError as e:
    print(f"Ошибка {e.status_code}: {e}")

Код	Причина
`401`	Неверный или отсутствующий API-ключ
`403`	Ваш тарифный план не включает доступ к API
`429`	Превышен лимит запросов (60 req/min)
`None`	Сервер недоступен или таймаут соединения

Безопасность

import os
from serpmax_client import SerpmaxAPI

client = SerpmaxAPI(api_key=os.environ["SERPMAX_API_KEY"])

# Linux / macOS
export SERPMAX_API_KEY="ваш_ключ"

# Windows (PowerShell)
$env:SERPMAX_API_KEY = "ваш_ключ"

Лицензия

MIT

FilesExpand file tree

README.ru.md

Latest commit

History