Поисковое API

Как звать

Каждая операция доступна двумя способами. Это одна и та же работа — разница только в том, сколько ждать.

GET https://search.the-project.it/search/<op>?…        ждём результат, но не дольше 25 с
GET https://search.the-project.it/search/async/<op>?…  сразу номер работы
GET https://search.the-project.it/search/result/<id>   результат по номеру

Синхронный вызов не быстрее — он ждёт. Если работа не уложилась в 25 секунд, он вернёт тот же номер и адрес результата, а работа продолжится: ни отмены, ни повторного запуска не происходит. Поэтому долгие операции удобнее звать сразу асинхронно.

Доступ

API открытое. Ни ключа, ни регистрации, ни заголовков — просто откройте адрес.

Единственный предел: не больше 300 запросов в час с одного адреса и 2 одновременно идущих работ. Это не про доступ и не про наши расходы — государственные реестры отвечают капчей на серию частых запросов, и предел бережёт работоспособность для всех сразу.

Ответ

Форма одна у всех операций и у всех трёх способов вызова — разбирать ответ должен один и тот же код, какую бы ручку ни дёрнули.

{
  "id": "9f1c…",              номер работы
  "op": "company",
  "status": "done",            running | done | error — что с работой
  "found": true,               нашли ли то, что искали
  "reason": null,              почему не нашли; заполнен при found = false
  "sources": {                 кто из источников ответил, а кто нет
    "egrul": { "ok": true },
    "courts": { "ok": false, "reason": "картотека закрыта для автозапросов" }
  },
  "warnings": [],              оговорки, не отменяющие ответ
  "data": { … },               данные; своя форма у каждой операции
  "cost": {
    "rub": 0.0312,             сколько запрос стоил нам в деньгах
    "calls": [ … ],            платные вызовы: модель, поисковый API
    "free": { "egrul": 1 }     бесплатные обращения — их считаем, но не в рублях
  },
  "started_at": "…", "finished_at": "…"
}

Два поля, которые легко перепутать

status ≠ found

status: "done" значит, что работа прошла без сбоя. Нашли ли при этом что-нибудь — говорит found. Успешный запрос, не нашедший компанию, это done и found: false.

sources

Здесь живёт главное правило сервиса: не проверили ≠ проверили и не нашли. Пустой ответ реестра и молчащий реестр выглядят одинаково в data и по-разному здесь. Прежде чем считать, что чего-то нет, посмотрите, отвечал ли источник.

Отказы

Тело отказа: {"error":{"code":"inn_invalid","message":"…"}}. Разбирать нужно code — он не меняется, в отличие от текста.

Операции

curl "https://search.the-project.it/search/crawl?site=example.ru&limit=100"

curl "https://search.the-project.it/search/ask?site=example.ru&q=%D0%B4%D0%B5%D0%BB%D0%B0%D0%B5%D1%82%20%D0%BB%D0%B8%20%D0%BA%D0%BE%D0%BC%D0%BF%D0%B0%D0%BD%D0%B8%D1%8F%20%D0%BF%D0%B5%D1%87%D0%B5%D0%BD%D1%8C%D0%B5&pages=8"

curl "https://search.the-project.it/search/site-info?site=example.ru"

curl "https://search.the-project.it/search/companies?okved=86.23&region=77&npType=UL"

curl "https://search.the-project.it/search/company?inn=7731016390"

curl "https://search.the-project.it/search/identify?site=example.ru"

curl "https://search.the-project.it/search/website?inn=7731016390"

Чего API не делает

Не обходит капчу и антибот-стены. Если сайт закрыт защитой от автоматических обращений, операция вернёт found: false и назовёт защиту в sources.site.reason — Cloudflare, DDoS-Guard, Qrator, Imperva, reCAPTCHA. Это ответ, с которым можно работать; «страниц нет» в таком случае было бы выводом о сайте, которого мы не делали.

Не проверяет суды и исполнительные производства: картотека арбитражных дел и банк данных ФССП закрыты для автоматических запросов. Об этом приходит warning, и «дел нет» из молчания не следует.