Частые вопросы

Главная → Частые вопросы → Сервисы аналитики → API Средних ставок

API Средних ставок

API позволяет получать данные сервиса «Средние ставки» прямо в ваше ПО, без перехода на ATI.SU.

Доступ к API — платный. Необходимо приобрести лицензию «API Средних ставок».

Лимит на количество запросов к API Средних ставок — до 10 000 в месяц. Чтобы увеличить лимит, напишите в отдел продаж: boards@ati.su.

API Средних ставок позволяет передавать информацию о средних ставках в ₽/км или в ₽ за весь маршрут, их разбросе и динамике для самых популярных направлений по России и за рубеж, а также о количестве грузов на ATI.SU по выбранному направлению в выбранный период.

Средние ставки обновляются один раз в день. Они всегда актуальны за вчерашний день — ставки за сегодня вы увидите завтра.

Подробнее о том, как рассчитываются средние ставки

Для интеграции с API потребуется разработка с вашей стороны. Мы поможем: предоставим документацию и инструкции по интеграции, а также окажем техническую поддержку.

Информация для разработчиков

Разберём методы API Средних ставок.

Как посмотреть лимит и остаток запросов

Чтобы узнать лимит на текущий период: сколько запросов уже выполнено, сколько осталось и когда сбросится счётчик, используйте метод `GET /license/v1/usage-statistics`.

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

{
    "monthly_limit": 10000,
    "current_period_usage": 500,
    "remaining_requests": 9500,
    "counter_reset_date": "2026-06-02T07:45:11.585Z"
}

Параметр ответа	Описание
monthly_limit	Месячный лимит на количество запросов
current_period_usage	Количество запросов, выполненных за текущий период
remaining_requests	Оставшееся количество запросов
counter_reset_date	Дата и время следующего сброса счётчика запросов в формате ISO-8601 UTC

После сброса начнётся новый период, а запросы снова станут доступны.

Дата сброса не привязана к дате окончания лицензии и может с ней не совпадать. Например, если лицензия куплена на 2 месяца, счётчик сбрасывается каждый месяц.

Если вы израсходуете весь лимит запросов до окончания периода, новые запросы станут доступны только после сброса счётчика. Например, если лимит 10 000 запросов закончится за 10 дней, отправить новые запросы получится после даты сброса.

Если вы ещё не начали использовать API, параметр `counter_reset_date` не возвращается.

Метод получения направлений

GET all_directions — показывает все направления, которые есть в сервисе «Средние ставки». Если направления нет — значит у нас недостаточно данных, чтобы выдать по нему значения средних ставок. Можно попробовать посмотреть данные по региону в целом.

Есть 6 типов кузова: закрытый, открытый, тентованный, рефрижератор, контейнер и трал. По какому-то направлению может не быть данных по одному или нескольким типам кузова. Мы покажем только доступные типы кузова.

Сами средние ставки метод all_directions не показывает.

Чтобы получить все направления для разных тоннажей, используйте новую версия метода v2/all_directions. Старая версия all_directions будет работать в течение года, но по нему можно получить информацию только для 20 т.

Чтобы настроить интеграцию, можно использовать демометоды, которые отдают нереальные данные.

Посмотреть структуру запроса и ответа метода all_directions можно здесь. Чтобы изучить, как работает демоверсия, выставите параметр demo=true.

Все примеры далее приведены на основе нереальных данных.

Примеры ответа метода all_directions

Первый пример

{
"FromCityId":3611,
"FromCity":"Москва, РФ",
"ToCityId":206,
"ToCity":"Рязань, РФ",
"FromRegionId":null,
"FromRegion":null,
"ToRegionId":null,
"ToRegion":null,
"DirectionInfo":{
   "CartypeTonnage":{
      "close":[
         5
      ],
      "tent":[
         20
      ]
   },
  "TonnageCartype":{
      "5":[
         "close"
      ],
      "20":[
         "tent"
      ]
   }
},
"RoundTripsInfo":null
}

Из примера видно, что в сервисе «Средние ставки» есть направление Москва — Рязань для 5 т с типом кузова закрытый (close). B для 20 т с типом кузова тент (tent). Для этого направления нет данных для кругорейса (RoundTripsInfo: null).

Второй пример

{
"FromCityId":72,
"FromCity":"Ижевск, РФ",
"ToCityId":null,
"ToCity":null,
"FromRegionId":null,
"FromRegion":null,
"ToRegionId":21,
"ToRegion":"Свердловская обл., РФ",
"DirectionInfo":{
   "CartypeTonnage":{
      "open":[
         1.5,
         3
      ],
      "ref":[
         3
      ]
   },
  "TonnageCartype":{
      "1.5":[
         "open"
      ],
      "3":[
         "ref",
         "open"
      ]
   }
},
"RoundTripsInfo":null
}

Из примера видно, что в сервисе «Средние ставки» есть направление Ижевск — Свердловская область для 1,5 т с типом кузова открытый (open) и для 3 т с типом кузова открытый (open) и рефрижератор (ref). Для этого направления нет данных для кругорейса (RoundTripsInfo) — для регионов никогда нет кругорейса.

Третий пример

{
"FromCityId":1,
"FromCity":"Санкт-Петербург, РФ",
"ToCityId":3611,
"ToCity":"Москва, РФ",
"FromRegionId":null,
"FromRegion":null,
"ToRegionId":null,
"ToRegion":null,
"DirectionInfo":{
   "CartypeTonnage":{
      "docker":[
         3
      ],
      "ref":[
         3
      ]
   },
  "TonnageCartype":{
      "3":[
         "ref",
         "docker"
      ]
   }
},
"RoundTripsInfo":{
   "CartypeTonnage":{
      "docker":[
         3
      ]
   },
   "TonnageCartype":{
      "3":[
         "docker"
      ]
   }
}
}

Из примера видно, что в сервисе «Средние ставки» есть направление Санкт-Петербург — Москва для 3 т с типом кузова контейнер (docker) и рефрижератор (ref). Для этого направления есть кругорейс (RoundTripsInfo) для типа 3 т с типом кузова контейнер (docker).

Метод получения ставок

POST average_prices — позволяет получить средние ставки и количество грузов по направлениям, которые есть в методе all_directions.

Метод отдаёт три цены в ₽/км или в ₽ за весь маршрут: среднюю и разброс ставок — от и до. А также количество уникальных грузов на ATI.SU по выбранному направлению в выбранный период.

Ставки можно запрашивать только по конкретному направлению и типу кузова из метода all_directions. Ставки по всем направлениям сразу запросить нельзя.

В запросе можно указать период, направление, тип кузова, тоннаж, тип ставки (с НДС или без НДС), нужны ли цены на кругорейс.

Также можно указать дискретность — Frequency. То есть выбрать, как нужно агрегировать данные: за день (day), неделю (week), месяц (month). Неделя — это всегда с понедельника по воскресенье. Месяц — это строго календарный месяц.

Потренироваться и посмотреть разные варианты выдачи вы можете бесплатно с помощью демометода average_prices.

Все примеры далее приведены на основе нереальных данных.

Примеры ответа метода average_prices

Первый пример

Запросим ставки без НДС (WithNds: false,) для закрытого типа кузова (CarType: close) по направлению Санкт-Петербург (CityId: 1) — Москва (CityId: 3611). Период — с 1 марта (DateFrom) по 2 марта (DateTo). Дискретность (Frequency) — day.

Запрос:

{
  "From": {
    "CityId": 1
  },
  "To": {
    "CityId": 3611
  },
  "CarType": "close",
  "Tonnage": 5,
  "DateFrom": "2022-03-01",
  "DateTo": "2022-03-02",
  "Frequency": "day",
  "WithNds": false,
  "RoundTrip": false
}

Ответ:

{
  "Data": [
    {
      "DateFrom": "2022-03-01",
      "DateTo": "2022-03-01",
      "Prices": {
        "UpperPrice": 30.8,
        "BottomPrice": 20.9,
        "AveragePrice": 25.9
      },
      "PricesInRub": {
        "UpperPrice": 22050.0,
        "BottomPrice": 14960.0,
        "AveragePrice": 18540.0
      },
      "LoadsCount": 433
    },
    {
      "DateFrom": "2022-03-02",
      "DateTo": "2022-03-02",
      "Prices": {
        "UpperPrice": 31.3,
        "BottomPrice": 21.3,
        "AveragePrice": 26.3
      },
      "PricesInRub": {
        "UpperPrice": 22410.0,
        "BottomPrice": 15250.0,
        "AveragePrice": 18830.0
      },
      "LoadsCount": 394
    }
  ],
  "Distance": 716,
  "WithNDS": false
}

Из примера видно, что в ответе вы получите ставки за каждый день — 1 и 2 марта. За 1 марта по запрошенному направлению и тоннажу средняя ставка (Prices.AveragePrice) — 25,9 ₽/км, а за 2 марта — 26,3 ₽/км. Средняя ставка за весь маршрут (PricesInRub.AveragePrice) — 18 540 ₽ и 18 830 ₽ соответственно. Ставки указаны без НДС (WithNDS: false).

Также из примера видно, что за 1 марта на сайте было 433 уникальных груза (LoadsCount). А за 2 марта — 394 груза.

Так же, как в примере выше, если вы запрашиваете период с 1 по 20 марта с дискретностью day, в ответе вы получите ставки за каждый из 20 дней.

Второй пример

Если вы запрашиваете период с 1 по 7 марта 2022 года с дискретностью week — со вторника по понедельник, то в ответе вы получите ставки за два периода:

с 1 по 6 марта (со вторника по воскресенье),
за 7 марта (понедельник на следующей неделе).

{
  "Data": [
    {
      "DateFrom": "2022-03-01",
      "DateTo": "2022-03-06",
      "Prices": {
        "UpperPrice": 33.3,
        "BottomPrice": 23.2,
        "AveragePrice": 28.3
      },
      "PricesInRub": {
        "UpperPrice": 23840.0,
        "BottomPrice": 16610.0,
        "AveragePrice": 20260.0
      },
      "LoadsCount": 630
    },
    {
      "DateFrom": "2022-03-07",
      "DateTo": "2022-03-07",
      "Prices": {
        "UpperPrice": 34.5,
        "BottomPrice": 24.3,
        "AveragePrice": 29.4
      },
      "PricesInRub": {
        "UpperPrice": 24700.0,
        "BottomPrice": 17400.0,
        "AveragePrice": 21050.0
      },
      "LoadsCount": 128
    }
  ],
  "Distance": 716,
  "WithNDS": true
}

Из примера видно, что за неделю с 1 по 6 марта по запрошенному направлению средняя ставка (Prices.AveragePrice) — 28,3 ₽/км, а за 7 марта — 29,4 ₽/км. Средняя ставка за весь маршрут (PricesInRub.AveragePrice) — 20 260 ₽ и 21 050 ₽ соответственно. Ставки указаны с НДС (WithNDS: true).

Также из примера видно, что за период с 1 по 6 марта на сайте было 630 уникальных грузов (LoadsCount), так как некоторые могли размещаться на сайте несколько дней. За 7 марта — 128 грузов.

Если вы запрашиваете период с 7 по 13 марта 2022 года с дискретностью week, в ответе вы получите ставки только за один период, так как это неделя с понедельника по воскресенье.

Третий пример

Если вы запрашиваете период с 1 марта по 2 апреля 2022 года с дискретностью month, в ответе вы получите два периода:

с 1 по 31 марта,
с 1 по 2 апреля.

{
  "Data": [
    {
      "DateFrom": "2022-03-01",
      "DateTo": "2022-03-31",
      "Prices": {
        "UpperPrice": 33.5,
        "BottomPrice": 22.8,
        "AveragePrice": 28.2
      },
      "PricesInRub": {
        "UpperPrice": 23990.0,
        "BottomPrice": 16320.0,
        "AveragePrice": 20190.0
      },
      "LoadsCount": 1166
    },
    {
      "DateFrom": "2022-04-01",
      "DateTo": "2022-04-02",
      "Prices": {
        "UpperPrice": 32.4,
        "BottomPrice": 21.0,
        "AveragePrice": 26.7
      },
      "PricesInRub": {
        "UpperPrice": 23200.0,
        "BottomPrice": 15040.0,
        "AveragePrice": 19120.0
      },
      "LoadsCount": 397
    }
  ],
  "Distance": 716,
  "WithNDS": true
}

Из примера видно, что за месяц с 1 по 31 марта по запрошенному направлению средняя ставка (Prices.AveragePrice) 28,2 ₽/км, а с 1 по 2 апреля — 26,7 ₽/км. Средняя ставка за весь маршрут (PricesInRub.AveragePrice) — 20 190 ₽ и 19 120 ₽ соответственно. Ставки указаны с НДС (WithNDS: true).

Количество уникальных грузов (LoadsCount) с 1 по 31 марта — 1 166. С 1 по 2 апреля — 397.

Почему данные иногда меняются

Значения за предыдущие недели могут незначительно меняться. Это связано с тем, что каждый день мы получаем новые данные от партнёров, и ставки пересчитываются с учётом новой информации.

Нужна консультация?

Чтобы получить подробную консультацию по интеграции через API, позвоните по телефону +7 812 602–01–31 с 9 до 18 МСК.

Вам помогла эта статья?

Как выгрузить средние ставки по нескольким направлениям

Выгодные направления