API Документация

API для получения статистики каналов и публикаций в мессенджере MAX

Авторизация

Все методы API требуют авторизации через токен. Токен можно передать тремя способами (приоритет в порядке перечисления):

1. Query параметр

GET /api/v1/channels/get?channelId=xxx&token=your_token

2. Заголовок Authorization

Authorization: Bearer your_token

3. Заголовок X-API-Token

X-API-Token: your_token
Как получить токен: Для получения токена используйте форму обратной связи. Если у вас уже есть токен, информацию о нем вы можете посмотреть в Личном кабинете.

Формат ответа

Успешный ответ

{
  "status": "ok",
  "response": {
    // данные ответа
  }
}

Ошибка

{
  "status": "error",
  "error": {
    "message": "Error message",
    "code": 400
  }
}

Методы каналов

GET/api/v1/channels/get

Получение информации о канале. Параметр channelId может быть UUID канала в системе MaxStat или slug (username) канала.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.

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

GET https://maxdash.ru/api/v1/channels/get?channelId=fontanka&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": {
    "id": "3bdf5276-5ece-4c68-bab5-d3c84c809491",
    "title": "«Фонтанка.ру»",
    "about": "Fontanka.ru — главная страница Петербурга Статистика канала: https://maxdash.ru/channel/fontanka Реклама: https://t.me/Feedbackfontanka",
    "avatar": "https://i.oneme.ru/i?r=BUFxtygYfQ8hp8NJRyp5v4T3l1nFPj8b8HMKDzyjrHIZh8jBEG6drJ4JA5PR67Y096vFHytuSFeq8nVn8TsBai5o&fn=w_1440",
    "participants_count": 12465,
    "ci_index": 14,
    "categories": ["Новости и СМИ"],
    "region": ["Санкт-Петербург"],
    "link": "https://max.ru/fontanka",
    "username": "fontanka",
    "created_at": 1729259209419
  }
}
GET/api/v1/channels/stat

Статистика канала. Возвращает общую статистику: подписчики, реакции, ER% и ERR%, средний охват постов (avg_post_reach, avg_post_reach_12h/24h/48h/7d), avg_adv_post_reach, post_per_day, daily_reach, посты, упоминания.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала: UUID в системе MaxStat или slug (username без @). Поиск по chat_id не поддерживается

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

GET https://maxdash.ru/api/v1/channels/stat?channelId=fontanka&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "«Фонтанка.ру»",
    "about": "Fontanka.ru — главная страница Петербурга Статистика канала: https://maxdash.ru/channel/fontanka Реклама: https://t.me/Feedbackfontanka",
    "username": "fontanka",
    "participants_count": 12465,
    "reactions_count": 15234,
    "er_percent": 1.22,
    "err_percent": 0.85,
    "ci_index": 14.0,
    "avg_post_reach": 8500,
    "avg_adv_post_reach": 4200,
    "avg_post_reach_12h": 7200,
    "avg_post_reach_24h": 8100,
    "avg_post_reach_48h": 8500,
    "avg_post_reach_7d": 9000,
    "post_per_day": 3.5,
    "daily_reach": 29750.0,
    "posts_count": 1250,
    "mentions_count": 42,
    "mentioning_channels_count": 15
  }
}
GET/api/v1/channels/posts

Публикации канала. Возвращает список публикаций канала с возможностью фильтрации по времени и скрытия репостов. Результаты сортируются по дате публикации (от новых к старым).

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.
limitnumberНет20Количество результатов на странице. Минимум: 1, максимум: 100. Если задано значение ≤ 0, используется значение по умолчанию
offsetnumberНет0Смещение для пагинации. Минимум: 0. Если задано отрицательное значение, устанавливается в 0
startTimenumberНетНе заданНачальная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только посты с date >= startTime. Если не задан, фильтрация не применяется
endTimenumberНетНе заданКонечная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только посты с date <= endTime. Если не задан, фильтрация не применяется
hideForwardsstringНетfalseСкрывать репосты. Принимает значение "true" или "false". Если true, исключаются посты, которые являются репостами (есть запись в channel_citations)

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

GET https://maxdash.ru/api/v1/channels/posts?channelId=fontanka&limit=20&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": {
    "count": 3,
    "total_count": 150,
    "channel": {
      "id": "3bdf5276-5ece-4c68-bab5-d3c84c809491",
      "title": "«Фонтанка.ру»",
      "about": "Fontanka.ru — главная страница Петербурга",
      "avatar": "https://i.oneme.ru/i?r=BUFxtygYfQ8hp8NJRyp5v4T3l1nFPj8b8HMKDzyjrHIZh8jBEG6drJ4JA5PR67Y096vFHytuSFeq8nVn8TsBai5o&fn=w_1440",
      "participants_count": 12465,
      "ci_index": 14,
      "categories": ["Новости и СМИ"],
      "region": ["Санкт-Петербург"],
      "link": "https://max.ru/fontanka",
      "username": "fontanka",
      "created_at": 1729259209419
    },
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "date": 1729259209419,
        "views": 5000,
        "link": "https://max.ru/fontanka/123",
        "text": "Текст поста",
        "body": {
          "mid": "123",
          "seq": 456,
          "text": "Текст поста",
          "attachments": []
        }
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "date": 1729259100000,
        "views": 4500,
        "link": "https://max.ru/fontanka/122",
        "text": "Другой пост",
        "body": {
          "mid": "122",
          "seq": 455,
          "text": "Другой пост",
          "attachments": []
        }
      },
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "date": 1729259000000,
        "views": 4000,
        "link": "https://max.ru/fontanka/121",
        "text": "Еще один пост",
        "body": {
          "mid": "121",
          "seq": 454,
          "text": "Еще один пост",
          "attachments": []
        }
      }
    ]
  }
}
GET/api/v1/channels/forwards

Пересылки (цитирования) канала. Возвращает список перепостов публикаций канала в других каналах. Результаты сортируются по дате публикации перепоста (от новых к старым).

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.
limitnumberНет20Количество результатов на странице. Минимум: 1, максимум: 100. Если задано значение ≤ 0, используется значение по умолчанию
offsetnumberНет0Смещение для пагинации. Минимум: 0. Если задано отрицательное значение, устанавливается в 0
startDatenumberНетНе заданНачальная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только перепосты с postDate >= startDate. Если не задан, фильтрация не применяется
endDatenumberНетНе заданКонечная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только перепосты с postDate <= endDate. Если не задан, фильтрация не применяется
extendednumberНет0Расширенный режим. Принимает значение 0 или 1. Если 1, в ответе добавляется поле channels с информацией о каналах, которые делали репосты

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

GET https://maxdash.ru/api/v1/channels/forwards?channelId=fontanka&limit=20&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": {
    "items": [
      {
        "forwardId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "sourcePostId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "postId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "postLink": "https://max.ru/channel-1/post-123",
        "postDate": 1729259209419
      },
      {
        "forwardId": "e5f6a7b8-c9d0-1234-ef01-234567890124",
        "sourcePostId": "f6a7b8c9-d0e1-2345-f012-345678901235",
        "postId": "a7b8c9d0-e1f2-3456-0123-456789012346",
        "postLink": "https://max.ru/channel-2/post-456",
        "postDate": 1729259100000
      }
    ],
    "channels": [
      {
        "id": "d4e5f6a7-b8c9-0123-def0-123456789013",
        "title": "Канал, который делал репосты",
        "about": "Описание канала",
        "avatar": "https://example.com/avatar.png",
        "participants_count": 5000,
        "ci_index": 10,
        "categories": ["Новости и СМИ"],
        "region": ["Москва"],
        "link": "https://max.ru/forward-channel",
        "username": "forward-channel",
        "created_at": 1729000000000
      }
    ]
  }
}
GET/api/v1/channels/subscribers

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

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.
limitnumberНет100Количество результатов на странице. Минимум: 1, максимум: 100. Если задано значение ≤ 0, используется значение по умолчанию
offsetnumberНет0Смещение для пагинации. Минимум: 0. Если задано отрицательное значение, устанавливается в 0
startDatenumberНетНе заданНачальная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой >= startDate. Если не задан или равен 0, фильтрация не применяется
endDatenumberНетНе заданКонечная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой <= endDate. Если не задан или равен 0, фильтрация не применяется
groupstringНетdayТип группировки данных. Возможные значения: hour, day, week, month. Если задано недопустимое значение, используется day

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

GET https://maxdash.ru/api/v1/channels/subscribers?channelId=fontanka&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": [
    {
      "period": "2024-01-01",
      "participants_count": 1000
    },
    {
      "period": "2024-01-02",
      "participants_count": 1010
    },
    {
      "period": "2024-01-03",
      "participants_count": 1020
    }
  ]
}
GET/api/v1/channels/views

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

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.
limitnumberНет100Количество результатов на странице. Минимум: 1, максимум: 100. Если задано значение ≤ 0, используется значение по умолчанию
offsetnumberНет0Смещение для пагинации. Минимум: 0. Если задано отрицательное значение, устанавливается в 0
startDatenumberНетНе заданНачальная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой >= startDate. Если не задан или равен 0, фильтрация не применяется
endDatenumberНетНе заданКонечная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой <= endDate. Если не задан или равен 0, фильтрация не применяется
groupstringНетdayТип группировки данных. Возможные значения: day, week, month. Если задано недопустимое значение, используется day. Группировка по часам (hour) больше не поддерживается

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

GET https://maxdash.ru/api/v1/channels/views?channelId=fontanka&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": [
    {
      "period": "2023-01-01",
      "views_count": 125000
    },
    {
      "period": "2023-01-02",
      "views_count": 132000
    },
    {
      "period": "2023-01-03",
      "views_count": 128500
    }
  ]
}
GET/api/v1/channels/avg-posts-reach

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

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.
limitnumberНет100Количество результатов на странице. Минимум: 1, максимум: 100. Если задано значение ≤ 0, используется значение по умолчанию
offsetnumberНет0Смещение для пагинации. Минимум: 0. Если задано отрицательное значение, устанавливается в 0
startDatenumberНетНе заданНачальная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой >= startDate. Если не задан или равен 0, фильтрация не применяется
endDatenumberНетНе заданКонечная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой <= endDate. Если не задан или равен 0, фильтрация не применяется
groupstringНетdayТип группировки данных. Возможные значения: hour, day, week, month. Если задано недопустимое значение, используется day

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

GET https://maxdash.ru/api/v1/channels/avg-posts-reach?channelId=fontanka&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": [
    {
      "period": "2024-01-01",
      "avg_posts_reach": 5000
    },
    {
      "period": "2024-01-02",
      "avg_posts_reach": 5200
    },
    {
      "period": "2024-01-03",
      "avg_posts_reach": 5100
    }
  ]
}
GET/api/v1/channels/er

ER% (Engagement Rate) метрика канала. Показывает процент пользователей, которые взаимодействуют с контентом относительно общего количества просмотров. Рассчитывается как (реакции + пересылки) / просмотры * 100. Результаты сортируются по периоду (от старых к новым).

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.
limitnumberНет100Количество результатов на странице. Минимум: 1, максимум: 100. Если задано значение ≤ 0, используется значение по умолчанию
offsetnumberНет0Смещение для пагинации. Минимум: 0. Если задано отрицательное значение, устанавливается в 0
startDatenumberНетНе заданНачальная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой >= startDate. Если не задан или равен 0, фильтрация не применяется
endDatenumberНетНе заданКонечная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой <= endDate. Если не задан или равен 0, фильтрация не применяется
groupstringНетdayТип группировки данных. Возможные значения: day, week, month. Если задано недопустимое значение, используется day

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

GET https://maxdash.ru/api/v1/channels/er?channelId=fontanka&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": [
    {
      "period": "2021-11-26",
      "er": 41.0
    },
    {
      "period": "2021-11-25",
      "er": 41.4
    },
    {
      "period": "2021-11-24",
      "er": 40.9
    }
  ]
}
GET/api/v1/channels/err

ERR% (Engagement Rate by Reach) метрика канала. Показывает процент подписчиков, которые просматривают публикации канала. Рассчитывается как (avg_views / subscribers) * 100, где avg_views - среднее количество просмотров на пост за период, subscribers - количество подписчиков в этот период. Результаты сортируются по периоду (от старых к новым).

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.
limitnumberНет100Количество результатов на странице. Минимум: 1, максимум: 100. Если задано значение ≤ 0, используется значение по умолчанию
offsetnumberНет0Смещение для пагинации. Минимум: 0. Если задано отрицательное значение, устанавливается в 0
startDatenumberНетНе заданНачальная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой >= startDate. Если не задан или равен 0, фильтрация не применяется
endDatenumberНетНе заданКонечная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой <= endDate. Если не задан или равен 0, фильтрация не применяется
groupstringНетdayТип группировки данных. Возможные значения: day, week, month. Если задано недопустимое значение, используется day

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

GET https://maxdash.ru/api/v1/channels/err?channelId=fontanka&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": [
    {
      "period": "2021-11-26",
      "err": 8.33
    },
    {
      "period": "2021-11-25",
      "err": 8.50
    },
    {
      "period": "2021-11-24",
      "err": 8.25
    }
  ]
}
GET/api/v1/channels/err48

ERR48% (Engagement Rate by Reach за 48 часов) метрика канала. Показывает процент подписчиков, которые просматривают публикации канала, рассчитанный на основе средних просмотров за 48 часов на протяжении недели. Рассчитывается как (avg_views48h / subscribers) * 100. Отличие от /channels/err: использует avg_views48h (среднее кол-во просмотров за 48 ч). Результаты сортируются по периоду (от старых к новым).

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.
limitnumberНет100Количество результатов на странице. Минимум: 1, максимум: 100. Если задано значение ≤ 0, используется значение по умолчанию
offsetnumberНет0Смещение для пагинации. Минимум: 0. Если задано отрицательное значение, устанавливается в 0
startDatenumberНетНе заданНачальная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой >= startDate. Если не задан или равен 0, фильтрация не применяется
endDatenumberНетНе заданКонечная дата фильтрации (Unix timestamp в миллисекундах). Возвращаются только периоды с датой <= endDate. Если не задан или равен 0, фильтрация не применяется
groupstringНетdayТип группировки данных. Возможные значения: day, week, month. Если задано недопустимое значение, используется day

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

GET https://maxdash.ru/api/v1/channels/err48?channelId=fontanka&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": [
    {
      "period": "2021-11-26",
      "err48": 8.33
    },
    {
      "period": "2021-11-25",
      "err48": 8.50
    },
    {
      "period": "2021-11-24",
      "err48": 8.25
    }
  ]
}
GET/api/v1/channels/mentions

Получить список упоминаний канала в других каналах. Возвращает информацию о постах в других каналах, где упоминается данный канал. Исключаются самоупоминания (когда канал упоминает сам себя). Результаты сортируются по дате публикации поста (от новых к старым).

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданAPI токен для авторизации. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.
startDatenumberНетНе заданПериод упоминания с (timestamp в миллисекундах). Используется timestamp сообщения (время публикации поста)
endDatenumberНетНе заданПериод упоминания по (timestamp в миллисекундах). Используется timestamp сообщения (время публикации поста)
limitnumberНет20Количество записей (по умолчанию 20, максимум 100)
offsetnumberНет0Смещение для пагинации (по умолчанию 0)
extendednumberНет0Если 1, вернется информация о каналах, которые упомянули целевой канал

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

GET https://maxdash.ru/api/v1/channels/mentions?token=your_token&channelId=fontanka&limit=10&offset=0&extended=1

Пример ответа:

{
  "status": "ok",
  "response": {
    "items": [
      {
        "mentionId": "550e8400-e29b-41d4-a716-446655440000",
        "mentionType": "channel",
        "postId": "mid.ffffc2031caab514019bdbf2b6a01c5e",
        "postLink": "https://max.ru/channel/123",
        "postDate": 1543487975,
        "channel": {
          "id": "3bdf5276-5ece-4c68-bab5-d3c84c809491",
          "title": "Название канала",
          "about": "Описание канала",
          "avatar": "https://example.com/avatar.jpg",
          "participants_count": 15000,
          "ci_index": 856,
          "categories": ["Новости и СМИ"],
          "region": ["Москва"],
          "link": "https://max.ru/news_channel",
          "username": "news_channel",
          "created_at": 1729000000000
        }
      },
      {
        "mentionId": "660e8400-e29b-41d4-a716-446655440001",
        "mentionType": "channel",
        "postId": "mid.ffffc21135a54a6a019bdbdf40de41cf",
        "postLink": "https://max.ru/another_channel/456",
        "postDate": 1543487209,
        "channel": {
          "id": "7c8e9f10-2b3c-4d5e-6f7a-8b9c0d1e2f3a",
          "title": "Другой канал",
          "about": "Описание другого канала",
          "avatar": "https://example.com/avatar2.jpg",
          "participants_count": 8500,
          "ci_index": 650,
          "categories": ["Технологии"],
          "region": ["Санкт-Петербург"],
          "link": "https://max.ru/another_channel",
          "username": "another_channel",
          "created_at": 1729100000000
        }
      }
    ]
  }
}

Методы публикаций

GET/api/v1/posts/get

Детальная информация о посте по UUID, mid (message ID) или url. В ответе — id, date, views, link, channel_id (UUID канала), forwarded_from (если репост), text, media (массив вложений). Поиск последовательно: UUID → mid → url. date в секундах.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
postIdstringДаНе заданИдентификатор поста: UUID (например 3bdf5276-5ece-4c68-bab5-d3c84c809491), mid (например 1002665528) или url (например https://max.ru/fontanka/130). Поиск последовательно по UUID → mid → url

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

GET https://maxdash.ru/api/v1/posts/get?postId=3bdf5276-5ece-4c68-bab5-d3c84c809491&token=your_token
// По mid: ?postId=1002665528
// По url: ?postId=https://max.ru/fontanka/130

Пример ответа:

{
  "status": "ok",
  "response": {
    "id": "3bdf5276-5ece-4c68-bab5-d3c84c809491",
    "date": 1523019187,
    "views": 9736,
    "link": "https://max.ru/fontanka/130",
    "channel_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "forwarded_from": null,
    "text": "Хотите узнать кто репостнул или поделился ссылкой на публикацию...",
    "media": []
  }
}
GET/api/v1/posts/stat

Статистика публикации (динамика просмотров и реакций). Возвращает текущую статистику поста (просмотры, реакции, комментарии, пересылки, репосты) и динамику роста просмотров за первые 15 дней после публикации. Массив views содержит динамику просмотров за первые 15 дней после публикации поста (только группировка по дням). Группировка по часам (hour) больше не поддерживается.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
postIdstringДаНе заданИдентификатор поста. Может быть UUID поста, mid (message ID из Max) или url (ссылка на пост). Поиск выполняется последовательно: сначала по UUID, затем по mid, затем по url
groupstringНетdayТип группировки данных для динамики просмотров. Возможные значения: day. Если задано недопустимое значение, возвращается ошибка. Группировка по часам (hour) больше не поддерживается

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

GET https://maxdash.ru/api/v1/posts/stat?postId=3bdf5276-5ece-4c68-bab5-d3c84c809491&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": {
    "viewsCount": 15234,
    "sharesCount": 89,
    "commentsCount": 12,
    "reactionsCount": 456,
    "forwardsCount": 3,
    "mentionsCount": 2,
    "forwards": [
      {
        "postId": "mid.ffffc2031caab514019bdbf2b6a01c5e",
        "postLink": "https://max.ru/news_channel/123",
        "postDate": 1704110400000
      },
      {
        "postId": "mid.ffffc21135a54a6a019bdbdf40de41cf",
        "postLink": "https://max.ru/tech_news/456",
        "postDate": 1704196800000
      }
    ],
    "mentions": [],
    "views": [
      {
        "date": "2023-01-01",
        "viewsGrowth": "5200"
      },
      {
        "date": "2023-01-02",
        "viewsGrowth": "8500"
      },
      {
        "date": "2023-01-03",
        "viewsGrowth": "12100"
      },
      {
        "date": "2023-01-04",
        "viewsGrowth": "14200"
      },
      {
        "date": "2023-01-05",
        "viewsGrowth": "15234"
      }
    ]
  }
}
GET/api/v1/posts/stat-multi

Статистика множества публикаций одним запросом. Оптимизированный endpoint для получения базовой статистики по множеству постов одним запросом. Параметр postsIds может содержать UUID постов, mid (message_id), url поста (например https://max.ru/fontanka/AZs8OdzhHLU) или комбинацию. Идентификаторы разделяются запятыми, пробелы автоматически удаляются. Максимум 50 постов в одном запросе. Если какой-то пост не найден, он просто не будет включен в результат (без ошибки).

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
channelIdstringДаНе заданИдентификатор канала. Может быть UUID канала в системе MaxStat или slug (username) канала.
postsIdsstringДаНе заданСписок идентификаторов постов через запятую. Может содержать UUID постов, mid (message_id), url поста (например https://max.ru/fontanka/AZs8OdzhHLU) или комбинацию. Пробелы автоматически удаляются. Максимум 50 постов

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

GET https://maxdash.ru/api/v1/posts/stat-multi?token=your_token&channelId=fontanka&postsIds=3bdf5276-5ece-4c68-bab5-d3c84c809491,7c8e9f10-2b3c-4d5e-6f7a-8b9c0d1e2f3a

Пример ответа:

{
  "status": "ok",
  "response": [
    {
      "postId": "3bdf5276-5ece-4c68-bab5-d3c84c809491",
      "viewsCount": 15234,
      "sharesCount": 89,
      "reactionsCount": 456,
      "commentsCount": 12,
      "url": "https://max.ru/fontanka/AZs8OdzhHLU"
    },
    {
      "postId": "7c8e9f10-2b3c-4d5e-6f7a-8b9c0d1e2f3a",
      "viewsCount": 8500,
      "sharesCount": 42,
      "reactionsCount": 210,
      "commentsCount": 8,
      "url": "https://max.ru/fontanka/AZvfU-dFbzs"
    }
  ]
}

Ключевые слова

GET/api/v1/words/mentions-by-period

Отслеживание динамики упоминаний и охвата ключевых слов или фраз по периодам. Подойдет для мониторинга упоминания бренда или персоны в публикациях. Возвращает количество упоминаний и охват ключевого слова за каждый период (день/неделя/месяц) запрошенного диапазона. Если не указаны startDate и endDate, поиск выполняется за последние 10 дней. Поиск выполняется с использованием полнотекстового поиска PostgreSQL с поддержкой русского языка. Результаты возвращаются в порядке убывания периода (от новых к старым).

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданAPI токен для авторизации. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
qstringДаНе заданКлючевое слово или фраза для поиска. Поддерживает синтаксис websearch_to_tsquery: поиск фразы ("точная фраза"), логическое ИЛИ (слово1 OR слово2), логическое И (слово1 AND слово2), исключение (-слово или NOT слово)
startDatenumberНет10 дней назадПериод упоминания с (timestamp в миллисекундах). По умолчанию: 10 дней назад
endDatenumberНетТекущий моментПериод упоминания по (timestamp в миллисекундах). По умолчанию: текущий момент
hideForwardsbooleanНетfalseИсключить упоминания в публикациях, являющихся репостами (true/1 или false/0). При hideForwards=true исключаются все публикации, помеченные как репосты (форварды)
groupstringНетdayГруппировка результатов: day (формат "YYYY-MM-DD"), week (формат "YYYY-WW", год-номер недели ISO), month (формат "YYYY-MM")
limitnumberНет100Количество периодов (по умолчанию 100, максимум 365)

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

GET https://maxdash.ru/api/v1/words/mentions-by-period?token=your_token&q=путин&startDate=1541289600000&endDate=1543881600000&group=day&limit=30

Пример ответа:

{
  "status": "ok",
  "response": {
    "items": [
      {
        "period": "2018-11-04",
        "mentions_count": 11,
        "views_count": 6781
      },
      {
        "period": "2018-11-03",
        "mentions_count": 27,
        "views_count": 13097
      }
    ]
  }
}
GET/api/v1/words/mentions-by-channels

Получение списка каналов с упоминаниями ключевых слов или фраз. Подойдет для мониторинга того, в каких каналах упоминается бренд или персона. Возвращает статистику по каждому каналу и подробную информацию о них. Если не указаны startDate и endDate, поиск выполняется за последние 10 дней. Поиск выполняется с использованием полнотекстового поиска PostgreSQL с поддержкой русского языка. Результаты сортируются по количеству упоминаний (от больших к меньшим).

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданAPI токен для авторизации. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token
qstringДаНе заданКлючевое слово или фраза для поиска. Поддерживает синтаксис websearch_to_tsquery: поиск фразы ("точная фраза"), логическое ИЛИ (слово1 OR слово2), логическое И (слово1 AND слово2), исключение (-слово или NOT слово)
startDatenumberНет10 дней назадПериод упоминания с (timestamp в миллисекундах). По умолчанию: 10 дней назад
endDatenumberНетТекущий моментПериод упоминания по (timestamp в миллисекундах). По умолчанию: текущий момент
hideForwardsbooleanНетfalseИсключить упоминания в публикациях, являющихся репостами (true/1 или false/0). При hideForwards=true исключаются все публикации, помеченные как репосты (форварды)
limitnumberНет20Количество каналов (по умолчанию 20, максимум 100)

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

GET https://maxdash.ru/api/v1/words/mentions-by-channels?token=your_token&q=путин&limit=10

Пример ответа:

{
  "status": "ok",
  "response": {
    "items": [
      {
        "mentions_count": 4544,
        "views_count": 78710,
        "last_mention_date": 1572539401
      },
      {
        "mentions_count": 1,
        "views_count": 900,
        "last_mention_date": 1572204557
      },
      {
        "mentions_count": 1,
        "views_count": 1053,
        "last_mention_date": 1570826223
      }
    ],
    "channels": [
      {
        "id": "3bdf5276-5ece-4c68-bab5-d3c84c809491",
        "title": "Новые каналы",
        "about": "Здесь автоматически публикуются новые каналы, зарегистрированные в Max и попавшие в индекс MaxDash.",
        "avatar": "//static10.maxdash.ru/channels/_100/a8/a82c47f8c5d7d1259ee13ed84a4be346.jpg",
        "participants_count": 259,
        "ci_index": 1301,
        "categories": ["Новости и СМИ"],
        "region": ["Москва"],
        "link": "max.ru/newchans",
        "username": "newchans",
        "created_at": 1476909773000
      },
      {
        "id": "7c8e9f10-2b3c-4d5e-6f7a-8b9c0d1e2f3a",
        "title": "Новости дня",
        "about": "Актуальные новости",
        "avatar": "//static10.maxdash.ru/channels/_100/b9/b92c47f8c5d7d1259ee13ed84a4be347.jpg",
        "participants_count": 1500,
        "ci_index": 856,
        "categories": ["Новости и СМИ"],
        "region": ["Москва"],
        "link": "max.ru/news",
        "username": "news",
        "created_at": 1476909774000
      }
    ]
  }
}

Справочники

GET/api/v1/database/categories

Список категорий каналов. Возвращает все доступные категории каналов в системе MaxStat. Поле code используется для фильтрации в других endpoints (например, /channels/search?category=tech). Поле name - это человекочитаемое название категории на русском языке. Список категорий относительно стабилен и редко меняется. Рекомендуется кэшировать результат на стороне клиента для оптимизации запросов.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token

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

GET https://maxdash.ru/api/v1/database/categories?token=your_token

Пример ответа:

{
  "status": "ok",
  "response": [
    {
      "code": "tech",
      "name": "Технологии"
    },
    {
      "code": "news",
      "name": "Новости и СМИ"
    },
    {
      "code": "food",
      "name": "Еда и кулинария"
    },
    {
      "code": "business",
      "name": "Бизнес"
    },
    {
      "code": "education",
      "name": "Образование"
    },
    {
      "code": "entertainment",
      "name": "Развлечения"
    },
    {
      "code": "sport",
      "name": "Спорт"
    },
    {
      "code": "auto",
      "name": "Автомобили"
    },
    {
      "code": "realty",
      "name": "Недвижимость"
    },
    {
      "code": "health",
      "name": "Здоровье"
    },
    {
      "code": "fashion",
      "name": "Мода и стиль"
    },
    {
      "code": "travel",
      "name": "Путешествия"
    },
    {
      "code": "finance",
      "name": "Финансы"
    },
    {
      "code": "politics",
      "name": "Политика"
    },
    {
      "code": "art",
      "name": "Искусство"
    },
    {
      "code": "music",
      "name": "Музыка"
    },
    {
      "code": "games",
      "name": "Игры"
    },
    {
      "code": "science",
      "name": "Наука"
    },
    {
      "code": "animals",
      "name": "Животные"
    },
    {
      "code": "kids",
      "name": "Дети"
    },
    {
      "code": "humor",
      "name": "Юмор"
    },
    {
      "code": "home",
      "name": "Дом и сад"
    },
    {
      "code": "beauty",
      "name": "Красота"
    },
    {
      "code": "people",
      "name": "Люди и блоги"
    },
    {
      "code": "social",
      "name": "Социальные сети"
    },
    {
      "code": "economy",
      "name": "Экономика"
    },
    {
      "code": "society",
      "name": "Общество"
    },
    {
      "code": "culture",
      "name": "Культура"
    },
    {
      "code": "religion",
      "name": "Религия"
    }
  ]
}
GET/api/v1/database/regions

Список регионов. Возвращает все доступные регионы России в системе MaxStat. Поле slug - это идентификатор региона, который может использоваться для фильтрации в других endpoints. Поле name - это человекочитаемое название региона на русском языке. Список регионов относительно стабилен и редко меняется. Рекомендуется кэшировать результат на стороне клиента для оптимизации запросов.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token

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

GET https://maxdash.ru/api/v1/database/regions?token=your_token

Пример ответа:

{
  "status": "ok",
  "response": [
    {
      "slug": "moskva",
      "name": "Москва"
    },
    {
      "slug": "sankt-peterburg",
      "name": "Санкт-Петербург"
    },
    {
      "slug": "novosibirsk",
      "name": "Новосибирск"
    },
    {
      "slug": "ekaterinburg",
      "name": "Екатеринбург"
    },
    {
      "slug": "kazan",
      "name": "Казань"
    },
    {
      "slug": "nizhniy-novgorod",
      "name": "Нижний Новгород"
    },
    {
      "slug": "chelyabinsk",
      "name": "Челябинск"
    },
    {
      "slug": "samara",
      "name": "Самара"
    },
    {
      "slug": "omsk",
      "name": "Омск"
    },
    {
      "slug": "rostov-na-donu",
      "name": "Ростов-на-Дону"
    },
    {
      "slug": "ufa",
      "name": "Уфа"
    },
    {
      "slug": "krasnoyarsk",
      "name": "Красноярск"
    },
    {
      "slug": "voronezh",
      "name": "Воронеж"
    },
    {
      "slug": "perm",
      "name": "Пермь"
    },
    {
      "slug": "volgograd",
      "name": "Волгоград"
    },
    {
      "slug": "krasnodar",
      "name": "Краснодар"
    },
    {
      "slug": "saratov",
      "name": "Саратов"
    },
    {
      "slug": "tyumen",
      "name": "Тюмень"
    },
    {
      "slug": "tolyatti",
      "name": "Тольятти"
    },
    {
      "slug": "izhevsk",
      "name": "Ижевск"
    }
  ]
}

Callback

Методы для настройки webhook-уведомлений: установка Callback URL, подписки на каналы и ключевые слова. Запросы к callback-эндпоинтам не отнимают лимит токена.

POST/api/v1/callback/set-callback-url

Установка Callback URL для webhook-уведомлений. URL, на который будут отправляться уведомления при срабатывании подписок. Должен быть валидным HTTP или HTTPS URL. Токен и callback_url можно передавать через query или form (application/x-www-form-urlencoded). Не отнимает лимит токена.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданAPI токен. Может быть передан через query, form, заголовок Authorization: Bearer <token> или X-API-Token
callback_urlstringДаНе заданURL для уведомлений. Валидный HTTP или HTTPS URL

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

POST https://maxdash.ru/api/v1/callback/set-callback-url
Content-Type: application/x-www-form-urlencoded

callback_url=https://example.com/webhook

Пример ответа:

{
  "status": "ok"
}
GET/api/v1/callback/get-callback-url

Получение настроенного Callback URL и информации об очереди уведомлений. Не отнимает лимит токена.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданAPI токен. Может быть передан через query, заголовок Authorization: Bearer <token> или X-API-Token

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

GET https://maxdash.ru/api/v1/callback/get-callback-url?token=your_token

Пример ответа:

{
  "status": "ok",
  "response": {
    "url": "https://example.com/webhook",
    "pending_update_count": 0,
    "last_error_date": null,
    "last_error_message": null
  }
}
GET/api/v1/callback/subscriptions-list

Список подписок пользователя для уведомлений через callback. Подписки могут быть на каналы (type: channel) или на ключевые слова (type: word). Не отнимает лимит токена.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданAPI токен. Может быть передан через query, form или заголовок Authorization / X-API-Token

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

GET https://maxdash.ru/api/v1/callback/subscriptions-list?token=your_token

Пример ответа:

{
  "status": "ok",
  "response": {
    "total_count": 2,
    "subscriptions": [
      {
        "subscription_id": 23221,
        "type": "channel",
        "channel": {
          "id": "3bdf5276-5ece-4c68-bab5-d3c84c809491",
          "link": "https://max.ru/fontanka",
          "peer_type": "channel",
          "username": "@fontanka",
          "title": "Фонтанка.ру",
          "about": "Fontanka.ru — главная страница Петербурга",
          "participants_count": 103116,
          "ci_index": 1301.53,
          "created_at": 1476909773
        },
        "created_at": 1571411216
      },
      {
        "subscription_id": 23222,
        "type": "word",
        "keyword": "ключевое слово",
        "created_at": 1571411300
      }
    ]
  }
}
POST/api/v1/callback/subscribe-channel

Создание или редактирование подписки на канал. При срабатывании на указанный Callback URL отправляются уведомления о новых постах канала. Перед использованием необходимо установить Callback URL через set-callback-url. Не отнимает лимит токена.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданAPI токен. Может быть передан через query, form, Authorization или X-API-Token
channel_idstringДаНе заданИдентификатор канала: slug (например fontanka), ссылка на канал (например https://max.ru/fontanka), или UUID канала в MaxStat
subscription_idnumberНетНе заданID существующей подписки. Если задан — обновление вместо создания

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

POST https://maxdash.ru/api/v1/callback/subscribe-channel
Content-Type: application/x-www-form-urlencoded

channel_id=fontanka&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": {
    "subscription_id": 1234
  }
}
POST/api/v1/callback/subscribe-word

Создание или редактирование подписки на поисковое слово/фразу. При появлении постов, содержащих ключевое слово, на Callback URL отправляются уведомления. Перед использованием — установить Callback URL через set-callback-url. Не отнимает лимит токена.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданAPI токен. Может быть передан через query, form, Authorization или X-API-Token
qstringДаНе заданПоисковое слово или фраза. Максимум 800 символов
subscription_idnumberНетНе заданID существующей подписки. Если задан — обновление вместо создания
strong_searchnumberНет0Точное совпадение: 1 — включено, 0 — выключено
categorystringНетНе заданФильтр по категории из справочника
regionstringНетНе заданФильтр по региону из справочника

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

POST https://maxdash.ru/api/v1/callback/subscribe-word
Content-Type: application/x-www-form-urlencoded

q=новости&token=your_token

Пример ответа:

{
  "status": "ok",
  "response": {
    "subscription_id": 123
  }
}
POST/api/v1/callback/unsubscribe

Отмена подписки на уведомления. Удаляет подписку по её subscription_id. Не отнимает лимит токена.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданAPI токен. Может быть передан через query, form или заголовок Authorization / X-API-Token
subscription_idnumberДаНе заданID подписки для отмены

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

POST https://maxdash.ru/api/v1/callback/unsubscribe
Content-Type: application/x-www-form-urlencoded

subscription_id=23221&token=your_token

Пример ответа:

{
  "status": "ok"
}

Использование

GET/api/v1/usage/stat

Информация об использовании текущего API токена. Возвращает массив по продуктам (API Stat, API Search и т.д.): тариф, израсходованные запросы, каналы/ключевые слова, срок действия.

Параметры:

ПараметрТипОбязательныйЗначение по умолчаниюОписание
tokenstringДаНе заданВаш API токен. Может быть передан через query параметр, заголовок Authorization: Bearer <token> или заголовок X-API-Token

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

GET https://maxdash.ru/api/v1/usage/stat?token=your_token

Пример ответа:

{
  "status": "ok",
  "response": [
    {
      "serviceKey": "api_stat_S",
      "spentRequests": "100/8000",
      "expiredAt": 1735689600,
      "spentChannels": "5/30"
    },
    {
      "serviceKey": "api_search_basic",
      "spentRequests": "50/500",
      "expiredAt": 1735689600,
      "spentKeywords": "12/100"
    }
  ]
}

Поля в элементах response:
- serviceKey — идентификатор продукта/тарифа (api_stat_S, api_search_basic и т.д.)
- spentRequests — использовано запросов, формат "N" или "N/лимит"
- expiredAt — Unix-время окончания периода (0 если без срока)
- spentChannels — только для API Stat: использовано каналов "N/лимит"
- spentKeywords — только для API Search: использовано ключевых слов "N/лимит"

Примеры использования

cURL

# Получение информации о канале
curl "https://maxdash.ru/api/v1/channels/get?channelId=channel-slug&token=your_token"

# Поиск каналов
curl "https://maxdash.ru/api/v1/channels/search?q=новости&limit=10&token=your_token"

# С использованием Authorization header
curl -H "Authorization: Bearer your_token" \
     "https://maxdash.ru/api/v1/channels/get?channelId=channel-slug"

JavaScript (fetch)

// С query параметром
const response = await fetch(
  'https://maxdash.ru/api/v1/channels/get?channelId=channel-slug&token=your_token'
);
const data = await response.json();

// С Authorization header
const response = await fetch(
  'https://maxdash.ru/api/v1/channels/get?channelId=channel-slug',
  {
    headers: {
      'Authorization': 'Bearer your_token'
    }
  }
);
const data = await response.json();

Python (requests)

import requests

# С query параметром
response = requests.get(
  'https://maxdash.ru/api/v1/channels/get',
  params={
    'channelId': 'channel-slug',
    'token': 'your_token'
  }
)
data = response.json()

# С Authorization header
response = requests.get(
  'https://maxdash.ru/api/v1/channels/get',
  params={'channelId': 'channel-slug'},
  headers={'Authorization': 'Bearer your_token'}
)
data = response.json()