Как устроен API КБЖУ

Адреса

• GET/search?q=

  Поиск По названию, бренду, сети или штрихкоду. Понимает названия блюд целиком, как их пишут люди и нейросети: «Плов с курицей и овощами», «Авокадо (половина)». Название с упаковки длиннее 80 знаков можно прислать целиком, поиск возьмёт его начало. limit задаёт число ответов от 1 до 20 (по умолчанию 10), а offset листает дальше

• GET/suggest?q=

  Подсказки при наборе Для строки поиска, которая подсказывает по буквам: на «моро» предложит мороженое, а не смородину, и назовёт подходящие бренды в brands. Отдаёт только id и названия, поэтому лимит разных продуктов не тратит. Цифры придут в карточке того, что выбрал человек

• GET/{id}

  Карточка продукта Всё о продукте по id из поиска: порции, штрихкоды и источник цифр. С Premium ещё состав и аллергены с упаковки, клетчатка, сахар, соль, витамины и минералы. На бесплатном тарифе поле premium_only назовёт, что из этого у продукта есть

• GET?ids=

  Несколько карточек сразу До 20 id через запятую, например весь дневник за день. Каких нет, придут списком в missing

• GET/barcode/{ean}

  КБЖУ по штрихкоду Коды EAN-13 и EAN-8. Если цифр по коду нет, API ответит 404, а если сам товар нам известен, назовёт его в product

• POST/parse

  Разбор еды словами и по фото JSON {"text": "200 г гречки и 2 яйца"}, фото тарелки в image (base64) или оба сразу. В ответе продукты, их вес и КБЖУ каждого в items и сумма в total. Обычно ответ приходит сразу. Если разбор идёт дольше 25 секунд, API ответит 202 с id, а готовый результат отдаст GET /parse/{id}. Бесплатно 50 разборов в месяц, с Premium 50 в сутки

• POST/label

  КБЖУ с фото этикетки Фото таблицы с упаковки в image (base64), название товара по желанию в text. В ответе калории, БЖУ, клетчатка, сахар и соль на 100 г или 100 мл, название, бренд, штрихкод и вес нетто, если они видны. Цифры приходят, только если таблицу подтвердило второе, независимое чтение снимка. Если таблица не читается, придёт ошибка label_unreadable, и фото не спишется. Бесплатно 3 фото в месяц, с Premium 150, с Diamond 1 000

Параметры поиска

• marketru или kz оставит товары одной страны
• typefood оставит обычные продукты, branded товары брендов, chain блюда сетей. Можно несколько через запятую
• brandТолько этот бренд или сеть, по brand.id из ответа: ?q=бургер&brand=burger-king
• fullfull=true вернёт в поиске карточки целиком, и второй запрос за составом не понадобится. На бесплатном тарифе карточка короче, поэтому там full=true считается как обычный поиск

Ответ

curl -H "X-Api-Key: ваш_ключ" \
  "https://perek.us/api/v1/foods/search?q=гречка&limit=5"

# карточка продукта и поиск по штрихкоду
curl -H "X-Api-Key: ваш_ключ" "https://perek.us/api/v1/foods/burger-king/vopper"
curl -H "X-Api-Key: ваш_ключ" "https://perek.us/api/v1/foods/barcode/4606068171360"

import requests

r = requests.get(
    "https://perek.us/api/v1/foods/search",
    params={"q": "гречка", "limit": 5},
    headers={"X-Api-Key": "ваш_ключ"},
    timeout=10,
)
for food in r.json()["foods"]:
    print(food["name"], food["per100"]["kcal"], "ккал")

// Node.js 18 и новее: ключ живёт на сервере
const url = new URL("https://perek.us/api/v1/foods/search");
url.searchParams.set("q", "гречка");
url.searchParams.set("limit", "5");

const res = await fetch(url, {
  headers: { "X-Api-Key": process.env.PEREK_API_KEY },
});
const { foods } = await res.json();
for (const food of foods) {
  console.log(food.name, food.per100.kcal, "ккал");
}

{
  "query": "воппер",
  "similar": false,
  "offset": 0,
  "more": true,
  "foods": [{
    "id": "burger-king/vopper",
    "name": "Воппер",
    "type": "chain",
    "brand": {"id": "burger-king", "name": "Бургер Кинг", "kind": "chain"},
    "per100": {"kcal": 262.77, "protein": 9.85, "fat": 16.06, "carbs": 19.34},
    "servings": [{"label": "Порция", "grams": 274.0}],
    "unit": "г",
    "market": "ru",
    "url": "https://perek.us/food/burger-king/vopper",
    "license": null
  }]
}

Карточка целиком

Её отдают /{id}, ?ids=, штрихкод и поиск с full=true. Сверх полей из поиска в ней есть:

aliases

Другие названия продукта

barcodes

Штрихкоды, по которым продукт находится

product

Производитель, страна и срок годности, а с Premium ещё состав и аллергены с упаковки

per100

У части продуктов, кроме КБЖУ, клетчатка, сахар, насыщенные жиры и соль. Это поля Premium

micronutrients

Витамины и минералы, если они известны. Тоже Premium

sources

Откуда взяты цифры: название источника и ссылка

checked, verified

Когда цифры сверили с источником и когда мы проверили их сами

premium_only

На бесплатном тарифе список того, что из скрытого у продукта есть

Лимиты

Сутки по UTC

Счётчики обнуляются в 00:00 UTC, это 03:00 по Москве

Лимиты на аккаунт

Общие для всех ключей аккаунта, поэтому лишние ключи лимит не прибавляют

Повторы не считаются

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

Поиск и карточки отдельно

Выдача поиска тратит свой лимит. Карточка продукта, штрихкод и поиск с full=true тратят лимит карточек, кроме бесплатного тарифа, где full=true считается обычным поиском. Если продукт уже пришёл вам сегодня в поиске, его карточка лимит не тратит

Потолок адреса

С одного IP можно сделать 2 000 запросов в сутки, а с Premium 20 000. Если запросы похожи на выкачивание справочника, лимиты аккаунта урезаются на сутки

Когда лимит кончился

Придёт ответ 429. Заголовок Retry-After скажет, через сколько секунд повторить, а тело назовёт тариф, где лимит выше, и его цену

Заголовки ответа

X-RateLimit-Remaining

Сколько запросов осталось в эту минуту

X-RateLimit-Remaining-Day

Сколько запросов осталось на сутки

X-Search-Foods-Remaining-Day

Сколько ещё разных продуктов сегодня отдаст поиск

X-Foods-Remaining-Day

Сколько ещё карточек разных продуктов на сутки

X-Api-Plan

Тариф аккаунта: free, premium или diamond

Retry-After

У ответа 429: через сколько секунд повторить

Ошибки

Тело любой ошибки: {"error": {"code": "...", "message": "..."}}. Текст в message по-русски, его можно показать человеку

400Неверный запрос

bad_query bad_limit bad_offset bad_market bad_type bad_brand bad_ids bad_barcode bad_body bad_text bad_image empty

401Нет ключа

unauthorized: ключ не передан, неверный или отозван

403Не входит в тариф

label_unavailable: чтение этикеток доступно с Premium

404Не найдено

not_found: такого продукта нет. Если товар по штрихкоду известен без цифр, его название придёт в product

413Большое фото

image_too_large: снимок больше 8 МБ

422Не разобрать

label_unreadable, failed: повтор того же фото или текста не поможет, а фото этикетки не спишется

429Лимит

rate_limited, parse_limit, label_limit. Повторите позже, срок в Retry-After

503Временно

disabled, parse_busy, label_busy: повторите чуть позже

Условия

Ссылка на нас

На бесплатном тарифе рядом с цифрами из API покажите ссылку «Данные: perek.us» на страницу продукта из поля url. С Premium ссылка по желанию

Коммерческий проект

Бесплатный тариф для некоммерческих проектов. Если приложение берёт оплату, показывает рекламу или работает на бизнес, подключите Premium. Кто выпустил первый ключ до 21 октября 2026 года, остаётся на прежних условиях

Ключ только на сервере

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

Без выкачивания

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

Открытые базы

Если поле license заполнено, позицию можно распространять на условиях этой лицензии: ODbL у Open Food Facts, CC BY 4.0 у финской Fineli и научных статей, NLOD 2.0 у норвежской Matvaretabellen

Источник у каждой цифры

Откуда взяты цифры и когда их сверили, показывают поля sources, checked и verified. Цифры средние, как на любой упаковке

Вопрос или поправка

Напишите на ekinin.k@skybots.ru

Для ИИ-агентов

• Справка одним файломТо же, что на этой странице, в Markdown для Cursor, Claude и других агентов
• Подсказка для чатаСкопируйте в чат агента, и он встроит API сам
• MCP-серверПоиск продуктов и штрихкоды прямо в чате агента, на тарифе Diamond