Карта сайта

Собирает адреса страниц сайта и показывает, из каких разделов он состоит. Поиск отвечает сниппетами, а не списком страниц, поэтому «собери всё с этого агрегатора» обычными запросами решается перебором из десятков запросов - карта отдаёт структуру одним вызовом.

POSThttps://srezai.ru/api/v1/map

Пример запроса

bash

curl -X POST https://srezai.ru/api/v1/map \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer srz_live_ВАШ_КЛЮЧ" \
  -d '{
    "url": "https://all-events.ru",
    "limit": 200,
    "selectPaths": ["organizers"],
    "excludePaths": ["/tag/", "/page/"]
  }'

Параметры тела

Тело запроса - JSON. Обязателен только url; неизвестные или недопустимые поля игнорируются, а не роняют запрос.

urlstringобязательный

Сайт или любая его страница, http/https. Схема и хост берутся из адреса, якоря и хвостовой слэш отбрасываются, поэтому site.ru и site.ru/ - один и тот же старт.

limitnumberнеобязательный

Сколько адресов вернуть, от 1 до 200 (по умолчанию 50). Это размер ответа, а не размер выборки: total показывает, сколько адресов нашлось всего, - видно, что выборку обрезали. Нецелое число округляется, а не отвергается.

searchstringнеобязательный

Оставить адреса, содержащие эту подстроку. Регистр и «ё» не важны, слова через пробел ищутся по отдельности. Сравнивается именно адрес: карта страницы не читает, поэтому для русских сайтов указывайте часть латинского пути - "organizers", а не "организаторы".

selectPathsstring[]необязательный

Оставить только адреса, содержащие любую из этих подстрок - по одной на элемент, до 10. Так целятся в раздел: selectPaths: ["organizers"] на агрегаторе событий оставит тысячи адресов организаторов вместо служебных страниц, которые иначе наберут всю выборку.

excludePathsstring[]необязательный

Выбросить адреса, содержащие любую из этих подстрок (до 10): архивы, теги, пагинация, служебные разделы. Работает вместе с selectPaths: сначала отбор, потом выброс.

includeSubdomainsbooleanнеобязательный

Считать своими и поддомены. По умолчанию false - в выборку попадают только адреса того же хоста. Адреса чужих доменов отбрасываются всегда, даже при true.

intentstringнеобязательный

Задача словами: "страницы организаторов конференций". Адреса упорядочиваются по смыслу под задачу, явный шум отсекается - и при limit меньше длины карты отрезается наименее похожее. Это замена угадыванию фрагмента пути: если у нужных страниц нет общего куска адреса, selectPaths не найдёт ничего, а intent поднимет нужные в начало списка. Параметр только упорядочивает то, что уже прошло фильтры по хосту, robots и подстрокам, и ничего не добавляет. Работает, если включён на стороне сервиса; иначе молча игнорируется, а вызов обслуживается как раньше.

Ответ

json

{
  "url": "https://all-events.ru",
  "origin": "https://all-events.ru",
  "total": 26111,
  "returned": 200,
  "pages": [
    "https://all-events.ru/organizatoram/organizers/ooo-romashka",
    "https://all-events.ru/organizatoram/organizers/…"
  ],
  "sections": [
    { "prefix": "/organizatoram/organizers/", "count": 3565 },
    { "prefix": "/ploshadki-dlya-meropriyatiji/", "count": 812 }
  ],
  "source": "sitemap",
  "sitemaps": [
    "https://all-events.ru/sitemap.xml",
    "https://all-events.ru/sitemap-files.xml"
  ],
  "outcome": "ok",
  "note": "",
  "credits": 20,
  "meta": { "tookMs": 3180 }
}

urlstringнеобязательный

Нормализованный адрес, с которого начали.

originstringнеобязательный

Схема и хост - по ним видно, какой сайт обошли.

totalnumberнеобязательный

Сколько адресов нашлось до обрезки по limit и уже с учётом search, selectPaths и excludePaths.

returnednumberнеобязательный

Сколько адресов в pages. По этому числу считаются кредиты.

pagesstring[]необязательный

Адреса - нормализованные, без дублей, не страницы. Когда карт несколько, адреса берутся по кругу между ними: иначе выборка из 200 адресов целиком состояла бы из первого файла карты, и разделы показывали бы один раздел вместо структуры сайта. Отбрасываются адреса, которые страницами не являются: картинки, скрипты, стили, архивы, резервные копии.

sectionsobject[]необязательный

Разделы сайта по возвращённым адресам: prefix (первые два сегмента пути) и count - сколько адресов в нём. Считается по выборке, а не по всему сайту, поэтому при малом limit показывает срез, а не полную картину.

sourcestringнеобязательный

Откуда взялись адреса: sitemap (карты сайта, в том числе названные в robots.txt) или links - ссылки со стартовой страницы, когда карт нет вовсе.

sitemapsstring[]необязательный

Какие карты сайта читались. Пусто, если карт не было.

outcomestringнеобязательный

Чем закончилось чтение: ok, blocked (сайт отвечает 403/401), unreachable (не ответил за отведённое время), empty (карт нет и ссылок нет). См. Когда сайт не пустил.

notestringнеобязательный

Человеческая причина, если она есть: 403, недоступность, отсутствие карт или «сайт отдал больше карт, чем мы читаем за один вызов» (читаем до 8). Пустая строка, когда объяснять нечего.

creditsnumberнеобязательный

Сколько кредитов списано фактически - эта же цифра уходит в журнал запросов. При нулевом результате credits: 0.

metaobjectнеобязательный

tookMs - сколько занял вызов.

Когда сайт не пустил: outcome: blocked

Часть сайтов закрыта от чтения и отвечает 403 или 401 - например, expomap.ru. Это не ошибка запроса: он проходит успешно (200), а в теле приходит outcome: "blocked" и пояснение. См. Ошибки.

json

{
  "url": "https://expomap.ru",
  "origin": "https://expomap.ru",
  "total": 0,
  "returned": 0,
  "pages": [],
  "sections": [],
  "source": "links",
  "sitemaps": [],
  "outcome": "blocked",
  "note": "Сайт отвечает 403/401 на наши запросы - обойти его мы не можем. Это не «страниц нет»: владелец закрыл доступ, и по этому адресу поможет только web_search по содержимому.",
  "credits": 0,
  "meta": { "tookMs": 1240 }
}

Цена

1 кредит за каждые 10 возвращённых адресов, минимум 1: limit: 200 - это 20 кредитов. Платится то, что реально пришло в pages, а не то, сколько адресов нашлось на сайте.

Ноль возвращённых адресов - ноль кредитов: сайт, который нас не пустил, или сайт без карт и ссылок не стоит ничего. Перед вызовом баланс проверяется по запрошенному limit, поэтому отказать по нехватке средств может и запрос, который в итоге стоил бы дешевле.

1 кредит = 0,10 ₽. Актуальная сетка - на странице тарифов, расход по услугам за сутки и неделю отдаёт get_usage.

Через MCP: map

Тот же функционал доступен агенту как инструмент map MCP-сервера - с теми же полями: url, limit, search, selectPaths, excludePaths, includeSubdomains. Ответ приходит текстом: адреса, найденное и возвращённое число, разделы с количеством адресов и источник. Когда за адресами нужен ещё и текст страниц - это чтение разделов сайта (crawl).