API калорийности и КБЖУ продуктов

Ключ за пару минут

1. ВойдитеПо почте, через Telegram или MAX, как в дневник питания. Если аккаунта ещё нет, он появится при входе
2. Выпустите ключВ личном кабинете одной кнопкой. Там же видно, сколько запросов осталось на сегодня
3. Отправьте запросПередайте ключ в заголовке X-Api-Key, и ответ придёт в JSON

Получить ключ

Что в базе

• 38 335товаров от 4 032 брендов
• 45 119штрихкодов EAN
• 1 133позиции из меню 8 сетей
• 32 654товара с составом с упаковки
• 374продукта и блюда без бренда
• 418позиций с витаминами и минералами
• 3 212товаров из Казахстана, у них market: "kz"
• Откуда цифрыИсточник у каждой позиции указан в поле sources

Запросы

• Адресhttps://perek.us/api/v1/foods
• Ключв заголовке X-Api-Key
• ОтветJSON, числа на 100 г, а у напитков на 100 мл

• GET/search?q=

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

• GET/suggest?q=

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

• GET/{id}

  Карточка продукта Всё о продукте по id из поиска: состав с упаковки, штрихкоды, витамины и минералы, источник цифр

• GET?ids=

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

• GET/barcode/{ean}

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

• marketru или kz оставит товары одной страны
• typefood оставит обычные продукты, branded товары брендов, chain блюда сетей. Можно несколько через запятую
• brandТолько этот бренд или сеть, по brand.id из ответа: ?q=бургер&brand=burger-king
• fullfull=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
  }]
}

Тарифы и лимиты

• Сутки по UTCСчётчики обнуляются в 00:00 UTC, это 03:00 по Москве
• Повторы не считаютсяПродукт, который уже приходил вам сегодня, не тратит лимит разных продуктов. Приложению, где люди едят одно и то же, его хватит с запасом
• Остаток в заголовкахX-RateLimit-Remaining, X-RateLimit-Remaining-Day и X-Foods-Remaining-Day. Когда лимит кончится, придёт ответ 429, а Retry-After подскажет, когда повторить
• Общий потолок адресаС одного IP можно сделать 2 000 запросов в сутки, а с Premium 20 000. Если запросы похожи на выкачивание справочника, лимиты аккаунта урезаются на сутки

Условия

• Ссылка на насРядом с цифрами из API покажите ссылку «Данные: perek.us» на страницу продукта из поля url. Это нужно на любом тарифе
• Ключ только на сервереИз мобильного приложения или кода страницы его достанут за минуту, и вашими лимитами начнут пользоваться чужие
• Без выкачиванияСправочник нельзя собирать целиком, раздавать или продавать как свою базу. Если ключ используют так, мы его отзываем
• Открытые базыЕсли поле license заполнено, позицию можно распространять на условиях этой лицензии: ODbL у Open Food Facts, CC BY 4.0 у финской Fineli и научных статей, NLOD 2.0 у норвежской Matvaretabellen
• Источник у каждой цифрыОткуда взяты цифры и когда их сверили, показывают поля sources, checked и verified
• Есть вопрос или поправка?Напишите на ekinin.k@skybots.ru

Вопросы