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- Лимиты
- не тратит
Список отчётов
/projects/api/v1/reports/get
Отчёты проекта от новых к старым.
Параметры query
-
tokenstring обязательныйКлюч API из настроек аккаунта — тот же, чтоkeyу методов инструментов. -
project_idint обязательныйID проекта. Виден в адресе страницы проекта и в ответе projects/get. -
limitintСколько последних отчётов отдать.0или без параметра — все.
Ответ
-
result[].idstringID отчёта — его передают вreport_id. -
result[].statusstringdone— отчёт сформирован,in progress— ещё нет. -
result[].datedateКогда отчёт заказан. -
result[].domainstringДомен проекта. -
result[].from, result[].todateПериод отчёта. -
result[].compare_from, result[].compare_todateПериод для сравнения — только у отчётов со сравнением.
Отчёт и ссылки на файлы
/projects/api/v1/report/get
Статус одного отчёта и ссылки на его файлы, если они уже сформированы. Если файла нет, его можно заказать через report/file/get, там же — данные отчёта в JSON.
Параметры query
-
tokenstring обязательныйКлюч API из настроек аккаунта — тот же, чтоkeyу методов инструментов. -
project_idint обязательныйID проекта. Виден в адресе страницы проекта и в ответе projects/get. -
report_idstring обязательныйID отчёта — полеidиз reports/get.
Ответ
-
result.statusstringdone— отчёт сформирован,in progress— ещё нет. -
result.datedateКогда отчёт заказан. -
result.domainstringДомен проекта. -
result.from, result.todateПериод отчёта. -
result.compare_from, result.compare_todateПериод для сравнения — только у отчётов со сравнением. -
result.files.docx, result.files.pdfobjectstatus—true, если файл есть;link— ссылка на скачивание или пустая строка.
Файл отчёта: Word, PDF или данные в JSON
/projects/api/v1/report/file/get
Формат выбирается параметром type.
docx,pdf— если файл уже есть, отдаёт ссылку. Если нет — ставит его на формирование и отвечаетin progress; повторный вызов, пока файл готовится, второй задачи не создаёт. Пока сам отчёт не сформирован, файл не заказывается — метод отвечаетin progress. Опрашивайте метод раз в несколько секунд, покаstatusне станетdone. Метод отдаёт ссылку, а не сам файл.json— данные отчёта сразу в ответе, без постановки задачи: те же, из которых собираются страница отчёта и файлы. Пока отчёт не сформирован —in progressи пустойdata.
Параметры query
-
tokenstring обязательныйКлюч API из настроек аккаунта — тот же, чтоkeyу методов инструментов. -
project_idint обязательныйID проекта. Виден в адресе страницы проекта и в ответе projects/get. -
report_idstring обязательныйID отчёта — полеidиз reports/get. -
typestringФормат выгрузки.
Ответ
-
result.files.*.statusstringdoneилиin progress. Ключ — запрошенныйtype. Обратите внимание: здесь строка, а вreport/get—true/false. -
result.files.docx.link, result.files.pdf.linkstringСсылка на скачивание; пустая, пока файл не готов. -
result.files.json.dataobjectДанные отчёта по разделам. Пустой массив — раздел не включён в отчёт или у него нет данных. Набор блоков зависит от настроек отчёта.Вложенные поля
-
metrikaobject|arrayЯндекс Метрика: посещаемость, источники, устройства, города, страницы, конверсии. -
keyword_dataobject|arrayПозиции: видимость, динамика запросов, запросы в ТОП, средняя позиция. В блоках таблиц позиций (paDynamics,paTop3Dynamics,paTop10Dynamics)shared_key— ключ гостевой ссылки на позиции за период отчёта (/projects/shared/{id}/positions?key=…), аregion_tables— разбивка простой таблицы на таблицы по регионам, если колонок поисковых систем больше четырёх. -
url_dataobject|arrayГруппы URL: рейтинг и URL с ростом. -
site_dataobject|arrayПараметры сайта: ИКС, индексирование, ссылки, интегральные показатели, конкуренты, KPI. -
directobject|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.