Наличие топлива на АЗС России одним GET-запросом

Два способа подключиться

Если у вас своя карта, берите чистый JSON. Если карты нет, встройте готовый виджет.

Первый запрос за 10 минут

Инструкция рассчитана на человека, который никогда не работал с API. Если что-то не получается на любом шаге, просто напишите нам и мы поможем.

curl --get "https://fbenz.ru/api/v1/partner/stations" \
  --data-urlencode "city=Москва" \
  -H "Authorization: Bearer fb_live_ВАШ_КЛЮЧ"

Invoke-RestMethod -Uri "https://fbenz.ru/api/v1/partner/stations?city=Москва" -Headers @{ Authorization = "Bearer fb_live_ВАШ_КЛЮЧ" }

{
  "stations": [{
    "id": "n1234567890",
    "lat": 55.7558,
    "lon": 37.6173,
    "brand": "Лукойл",
    "name": "Лукойл",
    "addr": "Ленинградский пр-т, 63",
    "fuel": {
      "status": "yes",
      // что есть и чего нет
      "fuels_now": "92,95,ДТ",
      "fuels_no": "100",
      // цены за литр, если водители их указали
      "prices": "92=58.4,95=63.2",
      // очередь машин: "", "0-5", "5-10", "10-20", "20+"
      "queue": "5-10",
      // лимит литров в одни руки (null = нет)
      "limit_l": 20,
      // особенности оплаты
      "no_cash": false,
      "fuel_cards_only": false,
      // подтверждений от водителей
      "confirmations": 3,
      // независимых живых устройств за этим статусом
      "real_count": 3,
      // true = статус держится на импортированных данных, а не на отметках людей
      "seeded": false,
      "updated": "2026-07-16 09:41:07",
      // отметка есть, но подтверждений ей пока не хватает
      "pending_status": "no",
      "pending_count": 1,
      // published · unconfirmed · conflict · no_data
      "resolution_reason": "unconfirmed",
      // не null только при resolution_reason = conflict
      "conflict": null
    }
  }],
  "count": 412,
  "as_of": "2026-07-16 09:45:00",
  "stale_after_hours": 24
}

Восемь методов закрывают весь сценарий

Все методы живут под /api/v1/partner, ключ передаётся в заголовке Authorization: Bearer <ключ>. Полная спецификация: openapi.json.

Поиск и фильтры прямо в API

Не хотите фильтровать на своей стороне: попросите сервер. Все параметры работают на /stations и /stations/all, считаются в базе до отдачи, поэтому ответ никогда не теряет подходящие станции из-за лимита страницы.

curl --get "https://fbenz.ru/api/v1/partner/stations" \
  --data-urlencode "city=Москва" \
  --data-urlencode "fuel=95" \
  --data-urlencode "brand=Лукойл" \
  --data-urlencode "status=yes,low" \
  -H "Authorization: Bearer fb_live_ВАШ_КЛЮЧ"

Ваши юзеры тоже могут ставить статусы

Пользователи вашего приложения отмечают наличие топлива так же, как водители на fbenz.ru: та же форма, те же правила, тот же вес голоса. Ваш бэкенд просто пересылает отметку одним POST-запросом с секретным ключом.

curl -X POST "https://fbenz.ru/api/v1/partner/stations/n1234567890/report" \
  -H "Authorization: Bearer fb_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "yes",
    "user_ref": "user-42",
    "fuels": ["92", "95"],
    "prices": {"95": 61.5},
    "lat": 55.7558, "lon": 37.6173,
    "external_id": "report-8f1c"
  }'

Что вернётся: "accepted": true, поле "remote", блок published с итогом пересчёта и блок fuel — та же самая витрина станции, что приходит в чтении. Перечитывать станцию после записи не нужно: обновляйте карточку у себя прямо из ответа. "remote": true значит, что голос принят без гео-подтверждения (координат нет, они далеко от станции или движение юзера физически невозможно): вес такого голоса ниже, и для публикации нужно подтверждение второго юзера. Отметка не обязана менять статус мгновенно: у станции те же пороги доверия, что и для водителей.

Отметка принята, но на карту не попала: подтверждения

Статус выходит на карту, когда за него набралось нужное число независимых устройств. По умолчанию правило такое:

Пока устройств не хватило, статус станции остаётся прежним, а сама отметка живёт в полях pending_status и pending_count. Они приходят в блоке fuel в каждом чтении: карточка АЗС, выборка по прямоугольнику и дельта. По ним рисуется плашка «ждёт подтверждения» и кнопка «подтверждаю», как это сделано в нашем виджете.

Отдельного метода для подтверждения нет и не нужно. Подтверждение это обычная отметка тем же статусом от другого пользователя: тот же POST /stations/{id}/report, тот же status, другой user_ref. Как только устройств хватило, статус публикуется и pending_count обнуляется. Один и тот же user_ref подтвердить сам себя не может: у устройства одно мнение о станции, повторная отметка заменяет предыдущую, а не удваивает её.

Два только что созданных пользователя не подтверждают друг друга. Устройства, впервые увиденные в пределах 10 минут, считаются одним человеком: это защита от накрутки, когда «толпу» заводят одной пачкой. На практике это заметно только в первые минуты жизни новой интеграции; дальше у ваших пользователей разный возраст и подтверждение проходит. Если ждать не хочется, порог снимается настройкой ниже.

Правило настраивается под вас. Для вашего ключа порог можно снять совсем (публиковать с первой отметки) или, наоборот, поднять до трёх и больше устройств. Настройка действует только на отметки, пришедшие через ваш ключ, и никогда не блокирует отметки обычных водителей в приложении. Текущее значение приходит в GET /widget/config полем confirm_min: 0 это общее правило из таблицы выше. Поменять порог можно по запросу, напишите нам.

Вы всегда знаете возраст данных

Данные собирают сами водители: отметка появляется в API через несколько минут. У каждого статуса есть updated, а у каждого ответа as_of.

Как устроена свежесть

• Отметка водителя попадает в API примерно за 5 минут.
• Статус живёт 24 часа (stale_after_hours в каждом ответе). Устаревший статус отдаётся как nodata.
• Устаревание и внутренние пересчёты не всегда видны в дельте, поэтому раз в час забирайте полный снапшот /stations. Его ETag считается по видимому состоянию: если ничего не изменилось, вернётся 304, почти бесплатный.

Нужна вся Россия без дельт

Качайте /stations/all раз в 10-15 минут с заголовком If-None-Match. Ничего не менялось: придёт 304, почти бесплатный. Менялось: забирайте страницы по next_cursor (или всё одним запросом с limit=30000). ETag тут общий на весь дамп, поэтому протухания и пересчёты он ловит сам, дельты и часовые снапшоты в этой схеме не нужны.

Рекомендуемый цикл для дельт

Лимиты

Лимиты не про оплату запросов, они защищают сервис от перегрузки: у каждого партнёра свой лимит в минуту и суточная квота. Текущее состояние приходит в заголовках каждого ответа:

// лимит и остаток в текущей минуте
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
// unix-время сброса минуты
X-RateLimit-Reset: 1784192460
// суточная квота и остаток
X-RateLimit-Daily-Limit: 50000
X-RateLimit-Daily-Remaining: 49212

При превышении придёт 429 с заголовком Retry-After: подождите указанное число секунд и повторите. Квота сбрасывается в 00:00 UTC.

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

Кеш выборки по прямоугольнику

Запросы виджет-ключом по bbox отдаются из общего кеша: одинаковый прямоугольник считается один раз на всех ваших зрителей. В ответе есть заголовок X-Fbenz-Cache: hit|miss. Принятая отметка сразу выбрасывает из кеша все прямоугольники, накрывающие эту АЗС, поэтому после записи следующее чтение уже свежее. Секретный ключ читает мимо кеша и получает точный прямоугольник без квантования, поэтому ETag у секретного и виджет-ключа на один и тот же bbox разные — это нормально.

Кеш настраивается под вас. Его можно выключить совсем (тогда каждый запрос считается заново и всегда отдаёт последнее состояние) или задать свою длительность в секундах, от нуля до часа. Дольше кеш — быстрее карта и меньше нагрузка, короче кеш — быстрее видно чужие свежие отметки; свои собственные отметки видны сразу в любом случае, потому что запись сбрасывает кеш по своей АЗС. По умолчанию кеш включён с общей длительностью сервиса. Поменять — напишите нам.

Тонкости, о которые спотыкаются

• /stations/all отдаёт страницы минимум по 100 записей: limit=1 вернёт 422. Максимум 30000.
• В адресной строке queue=20+ надо писать как queue=20%2B: плюс в query-строке означает пробел. В JSON-теле отчёта плюс пишется как есть.
• city= — это поиск, а не точное совпадение: опечатка молча найдёт ближайший город. Что именно нашлось, всегда видно в поле city ответа.
• resolution_reason описывает ЖИВОЙ пересчёт по отметкам. Показанный status может при этом прийти из импортированных данных, поэтому пара «status: yes + resolution_reason: unconfirmed» законна: на карте старое значение, а свежая отметка ждёт подтверждения.
• ETag и 304 работают на всех чтениях: выборка, дельта, полный дамп и карточка АЗС.

Карта под вашим брендом за один вечер

Кластеры, фирменные маркеры брендов АЗС, фильтр по топливу, карточки станций. Логотипа Fbenz нигде нет. Один тег HTML.

<iframe
  src="https://fbenz.ru/widget/?key=pk_live_ВАШ_КЛЮЧ&city=Москва"
  width="100%" height="480" style="border:0"
  allow="geolocation; fullscreen" title="Наличие топлива на АЗС"></iframe>

Куда вставить этот тег. Свой сайт: в HTML нужной страницы, например перед закрывающим </body>. Tilda: блок T123 «HTML-код». WordPress: блок «Пользовательский HTML». Bitrix: компонент «HTML-код». После вставки откройте страницу: карта должна появиться сразу.

Как именно проверяется домен: разрешив bank.ru, вы автоматически разрешаете и его поддомены (www.bank.ru, lk.bank.ru). Похожий чужой домен вроде bank.ru.evil.com не проходит. Запрос вообще без ссылающейся страницы (обращение с сервера, не из браузера) проходит: привязка защищает от копирования ключа на чужой сайт, это не криптография.

Карточка АЗС — та же, что в приложении fbenz

В виджете карточка станции собрана один в один с приложением: цветная плашка статуса с иконкой, крупный заголовок, строка «сколько подтверждений и когда обновлено», значок «данные устарели», блок «Это всё ещё актуально?» с кнопками «Да, подтверждаю» и «Изменилась», плашки «ждёт подтверждения» и «данные расходятся», марки топлива, цены за литр, лимит литров и способы оплаты. Ничего рисовать самому не нужно.

Если вы делаете свою карту на JSON API, тот же экран собирается из полей блока fuel: status и queue дают заголовок, confirmations и updated — строку доверия, seeded отвечает на вопрос «это отметки людей или импорт», real_count показывает, сколько независимых устройств за статусом, pending_status с pending_count рисуют ожидание подтверждения, а conflict (приходит только при resolution_reason: "conflict") даёт обе спорящие версии с их числом устройств.

Любой размер врезки

Карта подстраивается не под «телефон или десктоп», а под то, сколько места ей дал ваш контейнер. Проверено на пятнадцати размерах от 240×160 (крошечная карточка в списке) до 1600×900: ничего не наезжает друг на друга, полосы прокрутки внутри виджета нет, карточка АЗС и форма отметки всегда помещаются целиком.

• Узкая врезка: фильтры топлива превращаются в горизонтальную ленту, легенда цветов прячется ниже 340px ширины.
• Низкая врезка: кнопки темы и геолокации уезжают вниз, легенда прячется ниже 320px высоты, форма отметки становится компактной и прокручивается внутри себя, кнопка отправки остаётся приклеенной к низу.
• Вебвью на весь экран телефона: карточка АЗС открывается нижним шитом, карта двигается двумя пальцами, страница под ней продолжает скроллиться одним.
• Большой десктоп: элементы не растягиваются в бесконечность.

Одна практическая мелочь: у тега iframe обязательно задайте высоту. Без неё браузер поставит свои 150px, и карта окажется в узкой полоске. Ширину можно смело ставить в 100%, а высоту — хоть в пикселях, хоть в aspect-ratio, хоть на весь экран: раскладка пересоберётся сама, ваши стили для этого не нужны.

Пользователи ставят статусы прямо в виджете

В карточке каждой АЗС есть кнопка «Обновить статус»: зритель отмечает есть топливо, мало, очередь или нет, и какие марки в наличии. Отметка уходит через ваш публикуемый ключ и проходит те же проверки, что и отметки в приложении fbenz.ru: близость к АЗС (виджет спросит геолокацию, для неё нужен allow="geolocation" на iframe), защита от накрутки, кулдаун. Отметка без точной геопозиции принимается с меньшим весом и ждёт подтверждения рядом с АЗС. Кнопку можно выключить для вашего ключа: приём отметок это тумблер в вашем тарифе, напишите нам. Устройство зрителя виджет помнит анонимно, без входа и регистрации.

Если по АЗС уже есть отметка, которой не хватает подтверждений, виджет показывает её отдельной плашкой с кнопкой «Подтверждаю»: один тап, и статус выходит на карту. Автору его собственной отметки кнопка не показывается, подтвердить себя нельзя. Подробнее про пороги написано в разделе про отметки выше.

Внедрение с нуля: рабочий клиент за 15 минут

Скопируйте пример на своём языке: он забирает справочники, держит данные свежими через дельты и правильно реагирует на 304 и 429. Это весь код, который нужен для боевой интеграции.

import requests

BASE = "https://fbenz.ru/api/v1/partner"
KEY = "fb_live_ВАШ_КЛЮЧ"          # храните в секретах, не в коде
H = {"Authorization": f"Bearer {KEY}"}

# все города страны одним запросом (для меню, поиска, стартового экрана)
cities = requests.get(f"{BASE}/cities", headers=H, timeout=15).json()["cities"]

# полный снапшот всех АЗС страны (страницы по 10 000)
stations, cursor = [], ""
while True:
    r = requests.get(f"{BASE}/stations/all",
                     params={"cursor": cursor}, headers=H, timeout=60).json()
    stations += r["stations"]
    cursor = r.get("next_cursor") or ""
    if not cursor:
        break
as_of = r["as_of"]                # курсор для дельт, шаг 2
print("станций загружено:", len(stations))

import time

by_id = {st["id"]: st for st in stations}

while True:
    r = requests.get(f"{BASE}/stations/delta",
                     params={"updated_since": as_of}, headers=H, timeout=30)
    if r.status_code == 429:      # упёрлись в лимит: ждём и повторяем
        time.sleep(int(r.headers.get("Retry-After", "30")))
        continue
    r.raise_for_status()
    data = r.json()
    for st in data["stations"]:   # обновляем только изменившиеся
        by_id[st["id"]] = st
    as_of = data["as_of"]
    print("обновлено станций:", len(data["stations"]))
    time.sleep(120)               # раз в 2 минуты достаточно

const BASE = "https://fbenz.ru/api/v1/partner";
const KEY = "fb_live_ВАШ_КЛЮЧ";              // поменяйте на свой
const H = { Authorization: "Bearer " + KEY };
const byId = new Map();                       // ваша копия данных
const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
// таймаут на каждый запрос: сбой сети не подвесит ваш сервис (аналог timeout= в requests)
const get = (path) => {
  const c = new AbortController();
  const t = setTimeout(() => c.abort(), 30_000);
  return fetch(BASE + path, { headers: H, signal: c.signal }).finally(() => clearTimeout(t));
};

async function main() {
  // старт: полный снапшот всей страны, страницы по 10 000
  let cursor = "", asOf = "";
  do {
    const r = await get("/stations/all?cursor=" + encodeURIComponent(cursor));
    const data = await r.json();
    for (const st of data.stations) byId.set(st.id, st);
    asOf = data.as_of;
    cursor = data.next_cursor || "";
  } while (cursor);
  console.log("станций загружено:", byId.size);

  // дальше по кругу: только изменения
  while (true) {
    await sleep(120_000);                     // раз в 2 минуты достаточно
    const r = await get("/stations/delta?updated_since=" + encodeURIComponent(asOf));
    if (r.status === 429) {                   // лимит: подождать и повторить
      await sleep(1000 * (+r.headers.get("retry-after") || 30));
      continue;
    }
    const data = await r.json();
    for (const st of data.stations) byId.set(st.id, st);
    asOf = data.as_of;
    console.log("обновлено станций:", data.stations.length);
  }
}
main();

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

Ошибки, которые можно обработать кодом

Формат один: RFC 9457 (application/problem+json). В type код для программы, в detail объяснение для человека. В каждой ошибке есть request_id: назовите его нам, и мы найдём ваш запрос в логах за минуту.

{
  "type": "https://fbenz.ru/problems/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Minute quota of 120 requests exhausted; retry after 37s.",
  "limit": 120,
  "window": "60s",
  // назовите этот id в саппорте
  "request_id": "1a2b3c4d5e6f"
}

Два ключа: секретный и публикуемый

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