SEO-проекты · token

reports Отчёты: список, статус, файлы и данные

Группа работает с отчётами, которые заказаны в разделе «Отчёты» проекта: отдаёт их список и статус, файлы Word и PDF и данные отчёта в JSON. Сами отчёты через API не заказываются. Список, статус и JSON — синхронно, файлы Word и PDF — асинхронно: повторяйте report/file/get, пока не появится ссылка.

Адрес
/projects/api/v1/reports/get, /projects/api/v1/report/<метод>
Режим
синхронный; файлы Word и PDF — асинхронные, опросом
Форматы
docx, pdf, json
Лимиты
не тратит

Список отчётов

GET /projects/api/v1/reports/get

Отчёты проекта от новых к старым.

Параметры query

  • token string обязательный
    Ключ API из настроек аккаунта — тот же, что key у методов инструментов.
  • project_id int обязательный
    ID проекта. Виден в адресе страницы проекта и в ответе projects/get.
  • limit int
    Сколько последних отчётов отдать. 0 или без параметра — все.
    По умолчанию 0

Ответ

  • result[].id string
    ID отчёта — его передают в report_id.
  • result[].status string
    done — отчёт сформирован, in progress — ещё нет.
  • result[].date date
    Когда отчёт заказан.
  • result[].domain string
    Домен проекта.
  • result[].from, result[].to date
    Период отчёта.
  • result[].compare_from, result[].compare_to date
    Период для сравнения — только у отчётов со сравнением.

Отчёт и ссылки на файлы

GET /projects/api/v1/report/get

Статус одного отчёта и ссылки на его файлы, если они уже сформированы. Если файла нет, его можно заказать через report/file/get, там же — данные отчёта в JSON.

Параметры query

  • token string обязательный
    Ключ API из настроек аккаунта — тот же, что key у методов инструментов.
  • project_id int обязательный
    ID проекта. Виден в адресе страницы проекта и в ответе projects/get.
  • report_id string обязательный
    ID отчёта — поле id из reports/get.

Ответ

  • result.status string
    done — отчёт сформирован, in progress — ещё нет.
  • result.date date
    Когда отчёт заказан.
  • result.domain string
    Домен проекта.
  • result.from, result.to date
    Период отчёта.
  • result.compare_from, result.compare_to date
    Период для сравнения — только у отчётов со сравнением.
  • result.files.docx, result.files.pdf object
    status — true, если файл есть; link — ссылка на скачивание или пустая строка.

Файл отчёта: Word, PDF или данные в JSON

GET /projects/api/v1/report/file/get

Формат выбирается параметром type.

  • docx, pdf — если файл уже есть, отдаёт ссылку. Если нет — ставит его на формирование и отвечает in progress; повторный вызов, пока файл готовится, второй задачи не создаёт. Пока сам отчёт не сформирован, файл не заказывается — метод отвечает in progress. Опрашивайте метод раз в несколько секунд, пока status не станет done. Метод отдаёт ссылку, а не сам файл.
  • json — данные отчёта сразу в ответе, без постановки задачи: те же, из которых собираются страница отчёта и файлы. Пока отчёт не сформирован — in progress и пустой data.

Параметры query

  • token string обязательный
    Ключ API из настроек аккаунта — тот же, что key у методов инструментов.
  • project_id int обязательный
    ID проекта. Виден в адресе страницы проекта и в ответе projects/get.
  • report_id string обязательный
    ID отчёта — поле id из reports/get.
  • type string
    Формат выгрузки.
    docx
    файл Word, ссылка на скачивание
    pdf
    файл PDF, ссылка на скачивание
    json
    данные отчёта в ответе
    По умолчанию docx

Ответ

  • result.files.*.status string
    done или in progress. Ключ — запрошенный type. Обратите внимание: здесь строка, а в report/get — true/false.
  • result.files.docx.link, result.files.pdf.link string
    Ссылка на скачивание; пустая, пока файл не готов.
  • result.files.json.data object
    Данные отчёта по разделам. Пустой массив — раздел не включён в отчёт или у него нет данных. Набор блоков зависит от настроек отчёта.
    Вложенные поля
    • metrika object|array
      Яндекс Метрика: посещаемость, источники, устройства, города, страницы, конверсии.
    • keyword_data object|array
      Позиции: видимость, динамика запросов, запросы в ТОП, средняя позиция. В блоках таблиц позиций (paDynamics, paTop3Dynamics, paTop10Dynamics) shared_key — ключ гостевой ссылки на позиции за период отчёта (/projects/shared/{id}/positions?key=…), а region_tables — разбивка простой таблицы на таблицы по регионам, если колонок поисковых систем больше четырёх.
    • url_data object|array
      Группы URL: рейтинг и URL с ростом.
    • site_data object|array
      Параметры сайта: ИКС, индексирование, ссылки, интегральные показатели, конкуренты, KPI.
    • direct object|array
      Яндекс Директ — блоки отчёта (сводка, площадки, кампании, группы, объявления, конверсии, регионы, устройства, пол, возраст): chart, availableData и исходные строки Директа в report. Базовые метрики за неделю или месяц без хеша отчёта — в direct-statistics.

Ошибки

КодСообщениеКогда
50 access error Токен не передан, не найден, или у его владельца нет доступа к проекту.
51 wrong project id Проекта с таким project_id нет.
52 wrong request data report/get, report/file/get: не передан report_id или у проекта нет такого отчёта; для report/file/get — неверный type. Причина — в result.error.

Ссылки на файлы ведут на общую ссылку отчёта (/projects/shared/…) и открываются без авторизации — не публикуйте их там, где их могут увидеть посторонние.

Статус in progress в списке означает любое состояние, кроме «готов», — в том числе отчёт, сформировать который не удалось. Если статус не меняется долго, проверьте отчёт в интерфейсе.

Методы принимают GET и POST, но параметры читаются из query-строки. HTTP-код всегда 200: успех и ошибка различаются полями status и code.

Обратная связь и помощь
Если у вас есть идеи, как улучшить данный инструмент или остались вопросы по работе с ним, напишите в нашу службу поддержки, мы обязательно вам поможем.