Първи стъпки с FoodBase

Създай акаунт

Отиди на страницата за регистрация и си създай безплатен акаунт. Не ти трябва кредитна карта — безплатният план ти дава 100 API заявки на ден, което е напълно достатъчно за тестове и прототипи.

Генерирай API ключ

След като влезеш, отвори Dashboard > API Keys и натисни Create key. Дай му описателно име, например „Моето приложение“ или „Разработка“. Пълният ключ се показва само веднъж, затова го копирай и го запази на сигурно място (например във файл .env или в мениджър на пароли).

Ключът ти ще изглежда приблизително така: food_KV23NskbwXkKzi1yaPdPF1

Направи първата си заявка

Потърси хранителен продукт по име:

curl "https://foodbase.dev/v1/foods/search?q=banana&limit=3" \
  -H "X-API-Key: food_your_key_here"

Отговорът съдържа съвпадащите продукти с имена, марки, категории и основни хранителни стойности:

{
  "data": [
    {
      "id": "abc-123",
      "name_default": "Banana",
      "brand": null,
      "category": "Fresh fruits",
      "nutriscore": "a"
    }
  ],
  "total": 26080,
  "limit": 3,
  "offset": 0
}

Търсене по баркод

Ако правиш приложение за сканиране на баркодове, използвай баркод ендпойнта с EAN-13 или UPC код:

curl "https://foodbase.dev/v1/foods/barcode/5449000000996" \
  -H "X-API-Key: food_your_key_here"

Връща пълните данни за продукта, включително обобщение на хранителните стойности с калории, белтъчини, въглехидрати, мазнини, захари и фибри — всичко на 100 г.

Подробни хранителни вещества

За пълната разбивка на хранителните вещества (над 40 стойности, подредени по категории) използвай ендпойнта за nutrients. Той е наличен във всеки план — безплатният включва 25 разбивки на ден (следи хедъра X-RateLimit-Nutrients-Remaining), а платените планове са без ограничение:

curl "https://foodbase.dev/v1/foods/{id}/nutrients" \
  -H "X-API-Key: food_your_key_here"

Отговорът групира хранителните вещества в категории:

Макроси — енергия (kcal/kJ), белтъчини, въглехидрати, мазнини, фибри, захари, алкохол, нишесте
Мазнини — наситени, трансмазнини, моно-/полиненаситени, омега-3/6, холестерол
Минерали — натрий, калций, желязо, калий, магнезий, цинк и други
Витамини — A, C, D, E, B-комплекс (B1, B2, B6, B9, B12), ниацин

Групови заявки

Трябват ти няколко продукта наведнъж? Използвай bulk ендпойнта с до 100 ID-та:

curl -X POST "https://foodbase.dev/v1/foods/bulk" \
  -H "X-API-Key: food_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["id-1", "id-2", "id-3"]}'

Резултатите се връщат в същия ред като подадените ID-та — не е нужно да ги пренареждаш.

Пробвай AI ендпойнтите

Всеки план — включително безплатният — идва с месечен лимит от AI кредити (20 в безплатния). С тях работят ендпойнтите за компютърно зрение и анализ: разпознаване на продукт от снимка, разчитане на етикет с хранителни стойности, анализ на ястие или генериране на разбираемо AI резюме за всеки продукт. Всяко извикване има фиксирана цена в кредити, посочена в документацията, а всеки AI отговор съдържа хедъри X-Credits-Remaining.

Най-бързият начин да ги видиш в действие е фото playground-ът — качи снимка направо в браузъра със собствения си ключ. Или извикай някой директно:

curl -X POST "https://foodbase.dev/v1/analyze/product" \
  -H "X-API-Key: food_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"barcode": "3017620422003"}'

Лимити, които не ти пречат

Лимитите на секунда са token bucket-и: скоростта на плана ти е постоянната скорост (Free = 1 заявка/сек.), а отгоре получаваш burst от 5 пъти толкова — така страница, която пуска няколко паралелни заявки, просто работи. Всеки отговор съдържа хедъри, с които приложението ти може да следи използването:

X-RateLimit-Second-Limit: 1
X-RateLimit-Burst-Capacity: 5
X-RateLimit-Second-Remaining: 4
X-RateLimit-Daily-Limit: 100
X-RateLimit-Daily-Remaining: 97
X-RateLimit-Daily-Reset: 2026-04-14T23:59:59Z

Ако все пак получиш 429, той винаги идва с хедър Retry-After със секундите до следващия токен — спазвай го (повечето HTTP клиенти го правят автоматично) и ще се върнеш към 200-ци толкова бързо, колкото лимитерът позволява. Ако ти трябват много продукти наведнъж, POST /foods/bulk е една заявка вместо N.

Следващи стъпки

Разгледай документацията на API за всички налични ендпойнти и ги пробвай интерактивно
Разгледай базата данни сам в Product Explorer — всяка продуктова страница показва точно това, което връща API-то
Провери статистиката си, за да следиш дневните си заявки
Надгради плана си, когато ти трябва повече капацитет
Прочети ръководството ни за хранителните данни, за да разбереш покритието на данните