Wayback Machine API — справочник для архивистов
Internet Archive предоставляет HTTP-эндпоинты для программной работы с Wayback Machine: сохранения страниц, поиска по индексу снимков и проверки наличия снимков. Этот материал — краткий справочник для тех, кто автоматизирует работу с web.archive.org.
Не путать с Internet Archive CLI (ia) —
iaработает с каталогом archive.org (загрузка, скачивание и метаданные items). Здесь речь только о Wayback Machine.
Зачем архивисту программный API
- Проверка существования снимка перед публикацией ссылки.
- Сохранение страницы в Wayback Machine без браузера, из скриптов.
- Массовый поиск: например, все снимки сайта ведомства за 10 лет.
- Memento-роутинг: дать пользователю ссылку на ближайший по дате снимок.
Базовые URL
| Сервис | Эндпоинт |
|---|---|
| Wayback Machine | https://web.archive.org/web/ |
| SavePageNow 2 (SPN2) | https://web.archive.org/save |
| CDX Server API | https://web.archive.org/cdx/search/cdx |
| Availability API | https://archive.org/wayback/available |
| Memento TimeGate | https://web.archive.org/web/<URL> |
| Memento TimeMap | https://web.archive.org/web/timemap/link/<URL> |
CDX, Availability и Memento доступны без авторизации. SPN2 API требует ключей archive.org (см. ниже). Для всех сервисов действуют ограничения на частоту запросов.
1. SavePageNow 2 — отправить страницу на архивацию
Официальная документация — SPN2 Public API Page Docs (2023-01-22) (PDF в archive.org). Ниже — выжимка из неё.
Авторизация
SPN2 API требует авторизации одним из двух способов:
- S3-ключи archive.org (предпочтительно): получите их на archive.org/account/s3.php и передавайте заголовок
Authorization: LOW <access>:<secret>. - Cookies
logged-in-sigиlogged-in-userиз браузера (быстро устаревают).
Обязательно передавайте Accept: application/json, иначе сервер вернёт HTML-страницу.
Без авторизации можно сохранить отдельную страницу, просто открыв https://web.archive.org/save/<URL> в браузере, но с более жёсткими ограничениями.
Запрос на захват
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: LOW $IA_ACCESS:$IA_SECRET" \
-d "url=https://example.com/article" \
-d "if_not_archived_within=1d" \
https://web.archive.org/save
Ответ — идентификатор задания, а не готовый снимок:
{"url": "https://example.com/article", "job_id": "ac58789b-f3ca-48d0-9ea6-1d1225e98695"}
Проверка статуса
curl -H "Accept: application/json" \
-H "Authorization: LOW $IA_ACCESS:$IA_SECRET" \
https://web.archive.org/save/status/ac58789b-f3ca-48d0-9ea6-1d1225e98695
Пока захват идёт, status равен pending. При успехе возвращаются status: "success", original_url, timestamp, duration_sec, список resources и, при запросе, outlinks и screenshot. При ошибке — status: "error" и status_ext (например, error:too-many-redirects). Готовый снимок доступен по адресу https://web.archive.org/web/<timestamp>/<original_url>.
Параметры захвата
Значение параметра включается только строками 1 или on.
| Параметр | Что делает |
|---|---|
capture_all=1 | Сохранить страницу, даже если она отвечает ошибкой (HTTP 4xx/5xx); по умолчанию такие ответы не сохраняются |
capture_outlinks=1 | Также сохранить ссылки со страницы (не более 100). Документация просит не включать без необходимости |
capture_screenshot=1 | Сделать полный скриншот страницы в PNG |
if_not_archived_within=<timedelta> | Не сохранять заново, если есть снимок новее указанного срока (например, 1d, 30d) |
force_get=1 | Захват простым HTTP GET без браузера |
skip_first_archive=1 | Не проверять, первый ли это снимок URL (ускоряет захват) |
delay_wb_availability=1 | Снимок появится в Wayback Machine примерно через 12 часов (снижает нагрузку на IA) |
js_behavior_timeout=<N> | Сколько секунд выполнять JS-поведения (прокрутка и т. п.); 0 ускоряет захват |
outlinks_availability=1 | Вернуть время последнего снимка для каждой исходящей ссылки |
email_result=1 | Прислать отчёт на e-mail аккаунта |
Python
import os
import time
import requests
HEADERS = {
"Accept": "application/json",
"Authorization": f"LOW {os.environ['IA_ACCESS']}:{os.environ['IA_SECRET']}",
}
def save_url(url: str, timeout: int = 180) -> str | None:
r = requests.post(
"https://web.archive.org/save",
headers=HEADERS,
data={"url": url, "if_not_archived_within": "1d"},
timeout=60,
)
r.raise_for_status()
job = r.json()
if "job_id" not in job:
raise RuntimeError(job)
deadline = time.time() + timeout
while time.time() < deadline:
time.sleep(5)
s = requests.get(
f"https://web.archive.org/save/status/{job['job_id']}",
headers=HEADERS, timeout=30,
).json()
if s["status"] == "success":
return f"https://web.archive.org/web/{s['timestamp']}/{s['original_url']}"
if s["status"] == "error":
raise RuntimeError(s.get("status_ext"), s.get("message"))
return None
print(save_url("https://example.com/article"))
Готовая обёртка над тем же API — waybackpy (WaybackMachineSaveAPI).
Ограничения SPN2
По документу 2023 года: не больше 12 захватов в минуту для авторизованных пользователей и 4 для анонимных. Есть также предел одновременных заданий: при его превышении API возвращает ошибку. Другие ограничения: соединение с сайтом — до 10 с, посещение страницы — до 50 с, весь захват — до 2 мин, не больше 3 редиректов, файл — до 2 ГБ. Актуальные значения могут отличаться: ориентируйтесь на ответы API (HTTP 429 и сообщения об ошибках).
Когда SPN2 недостаточно
SavePageNow рассчитан на отдельные страницы. Для сотен и тысяч URL и для целых сайтов соберите собственный архив (Browsertrix, Wget) и храните его у себя или в репозитории.
Загрузка WARC/WACZ в item на archive.org через ia не добавляет страницы в Wayback Machine. Файлы будут доступны как item для скачивания, но не как снимки в web.archive.org/web/.... В индекс Wayback Machine попадают захваты самого IA, а также партнёрские коллекции (Archive-It и соглашения с IA).
2. CDX Server API — индекс снимков
CDX API возвращает список снимков по URL, префиксу, хосту или домену. Документация: wayback-cdx-server README.
Запрос: все снимки одного URL
curl 'https://web.archive.org/cdx/search/cdx?url=ruarxive.org/&limit=3'
Строка ответа — поля через пробел, по умолчанию urlkey timestamp original mimetype statuscode digest length:
org,ruarxive)/ 20180511081052 https://ruarxive.org/ text/html 200 Q3M75PLO6Z7NE5GSJBPCCN4NBFF6FYIQ 6673
С output=json — массив массивов, первая строка содержит названия полей:
[
["urlkey", "timestamp", "original", "mimetype", "statuscode", "digest", "length"],
["org,ruarxive)/", "20180511081052", "https://ruarxive.org/", "text/html", "200", "Q3M75PLO6Z7NE5GSJBPCCN4NBFF6FYIQ", "6673"]
]
Параметры CDX
| Параметр | Что делает |
|---|---|
url= | URL; адрес передаётся как есть (кириллические домены — в punycode или percent-encoding), SURT-ключ сервер строит сам |
matchType=exact | Точное совпадение (по умолчанию) |
matchType=prefix | Все URL под путём; то же, что url=example.com/news/* |
matchType=host | Все URL на хосте |
matchType=domain | Хост и все по ддомены; то же, что url=*.example.com |
from=2024, to=20261231 | Диапазон дат (от 1 до 14 цифр yyyyMMddhhmmss) |
filter=statuscode:200 | Фильтр по полю (Java-regex); ! в начале инвертирует. Параметр можно повторять |
collapse=urlkey | Схлопнуть соседние строки с одинаковым значением поля (collapse=timestamp:8 — одна запись в день) |
fl=timestamp,original | Какие поля вернуть |
limit=N, limit=-N | Первые или последние N строк |
offset=M | Пропустить M строк (плохо масштабируется) |
showResumeKey=true, resumeKey= | Постраничный обход больших выборок |
output=json | JSON вместо текста |
Если limit не указан, сервер отдаёт все записи до своего внутреннего предела. Для широких запросов (prefix, domain) задавайте limit и используйте resumeKey.