Nutrola Nutrition Data API: Jak mohou vývojáři přistupovat k naší databázi potravin

Chystáte se vyvinout aplikaci zaměřenou na zdraví, fitness nebo potraviny? Jedním z největších problémů, kterým budete čelit, jsou výživové údaje. Potřebujete přesné informace o kaloriích a makroživinách pro tisíce potravin, musíte pokrýt mezinárodní produkty a zajistit, aby byly aktuální, jak výrobci mění složení svých výrobků.

Většina vývojářů začíná stahováním dat z otevřených vládních databází, jako je USDA FoodData Central. To vám poskytne základ, ale nezahrnuje značkové produkty z 47 zemí, jídla z restaurací ani tisíce regionálních potravin, které skuteční uživatelé konzumují každý den. Vyplnit tyto mezery vlastními silami znamená roky práce na kuraci dat.

Nutrola Nutrition Data API poskytuje vývojářům přístup k téže ověřené databázi potravin, která pohání naši aplikaci — více než 3 miliony položek, zahrnující suroviny, značkové produkty, jídla z restaurací a složené recepty. Každý záznam je ověřen naším vícestupňovým systémem kontroly kvality, který důvěřuje více než 2 miliony uživatelů.

Tento průvodce pokrývá vše, co potřebujete vědět pro začátek práce s naším API: architektura, autentizace, koncové body, limity rychlosti a příklady kódu z reálného světa.

Přehled API

Nutrola Nutrition Data API je RESTful JSON API. Provádíte HTTP požadavky a dostáváte JSON odpovědi. SDK nejsou vyžadována, ale pro pohodlí poskytujeme klientské knihovny pro Python, JavaScript a Swift.

Základní URL

https://api.nutrola.com/v1

Všechny koncové body jsou poskytovány přes HTTPS. Požadavky přes obyčejné HTTP jsou odmítány.

Klíčové funkce

Funkce	Popis
Vyhledávání potravin	Full-textové vyhledávání napříč 3M+ položkami potravin s filtrováním podle kategorie, značky a země
Vyhledávání podle čárového kódu	Získejte výživové údaje podle UPC, EAN nebo jiných formátů čárového kódu
Detaily výživy	Kompletní výživový profil pro jakoukoli potravinu (70+ živin včetně mikronutrientů)
Velikosti porcí	Standardní a alternativní velikosti porcí s gramovými převody
Analýza receptů	Odeslat seznam ingrediencí a získat kombinované výživové údaje
Kategorie potravin	Procházejte hierarchickou taxonomii kategorií potravin
Seznam značek	Hledejte a procházejte výrobce značkových potravin
Automatické doplňování	Rychlé návrhy při psaní pro vyhledávací rozhraní potravin

Formát odpovědi

Všechny odpovědi mají konzistentní strukturu:

{
  "status": "success",
  "data": { },
  "meta": {
    "request_id": "req_abc123",
    "rate_limit_remaining": 245,
    "rate_limit_reset": "2026-03-10T15:00:00Z"
  }
}

Odpovědi s chybami obsahují strojově čitelný chybový kód a zprávu pro uživatele:

{
  "status": "error",
  "error": {
    "code": "FOOD_NOT_FOUND",
    "message": "Žádný záznam potraviny neodpovídá zadanému ID.",
    "request_id": "req_xyz789"
  }
}

Autentizace

Všechny požadavky na API vyžadují API klíč, který se předává v hlavičce Authorization.

Získání API klíče

1. Vytvořte si vývojářský účet na developer.nutrola.com
2. Přejděte do sekce API klíčů ve svém panelu
3. Vygenerujte nový klíč a specifikujte potřebné rozsahy
4. Klíč bezpečně uložte — bude zobrazen pouze jednou

Použití API klíče

Zahrňte klíč do každé hlavičky požadavku:

Authorization: Bearer YOUR_API_KEY

Příklad s curl:

curl -H "Authorization: Bearer ntr_live_abc123def456" \
  https://api.nutrola.com/v1/foods/search?q=chicken+breast

Rozsahy API klíče

Rozsah	Úroveň přístupu
foods:read	Vyhledávání a získávání dat o potravinách (nejběžnější)
barcodes:read	Vyhledávání podle čárového kódu
recipes:analyze	Analýza výživy receptů
brands:read	Přístup k adresáři značek
categories:read	Taxonomie kategorií potravin

Klíče mohou být omezeny na konkrétní funkce. Klíč s pouze foods:read nemůže přistupovat k vyhledávání podle čárového kódu. To dodržuje princip minimálního oprávnění — požadujte pouze ty rozsahy, které vaše aplikace potřebuje.

Hlavní koncové body

Vyhledávání potravin

Vyhledejte v databázi podle názvu, klíčového slova nebo fráze.

GET /v1/foods/search

Parametry:

Parametr	Typ	Povinný	Popis
q	string	Ano	Vyhledávací dotaz (např. "grilované kuřecí prso")
category	string	Ne	Filtrování podle kategorie potravin (např. "mléčné výrobky", "zelenina")
brand	string	Ne	Filtrování podle názvu značky
country	string	Ne	ISO 3166-1 alpha-2 kód země (např. "US", "DE", "JP")
verified_only	boolean	Ne	Vrátit pouze položky s ověřenými daty (výchozí: true)
page	integer	Ne	Číslo stránky pro stránkování (výchozí: 1)
per_page	integer	Ne	Výsledky na stránku, max 50 (výchozí: 20)

Příklad požadavku:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.nutrola.com/v1/foods/search?q=greek+yogurt&country=US&per_page=5"

Příklad odpovědi:

{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "food_8f2k9d",
        "name": "Gřecký jogurt, obyčejný, bez tuku",
        "brand": null,
        "category": "mléčné výrobky",
        "country": "US",
        "verified": true,
        "source": "USDA",
        "nutrition_per_100g": {
          "calories": 59,
          "protein": 10.2,
          "carbohydrates": 3.6,
          "fat": 0.4,
          "fiber": 0,
          "sugar": 3.2,
          "sodium": 36
        },
        "default_serving": {
          "description": "1 nádoba (170g)",
          "grams": 170
        }
      }
    ],
    "total_results": 342,
    "page": 1,
    "per_page": 5
  }
}

Získání detailů o potravině

Získejte kompletní výživový profil pro konkrétní potravinu.

GET /v1/foods/{food_id}

Příklad požadavku:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.nutrola.com/v1/foods/food_8f2k9d"

Odpověď detailu zahrnuje kompletní rozpis živin — více než 70 živin včetně všech vitamínů, minerálů, aminokyselin a profilů mastných kyselin. Obsahuje také všechny dostupné velikosti porcí a jejich gramové ekvivalenty.

Částečná odpověď (klíčové živiny):

{
  "status": "success",
  "data": {
    "id": "food_8f2k9d",
    "name": "Gřecký jogurt, obyčejný, bez tuku",
    "nutrition_per_100g": {
      "calories": 59,
      "protein": 10.2,
      "carbohydrates": 3.6,
      "fat": 0.4,
      "fiber": 0,
      "sugar": 3.2,
      "saturated_fat": 0.1,
      "monounsaturated_fat": 0.1,
      "polyunsaturated_fat": 0,
      "cholesterol": 5,
      "sodium": 36,
      "potassium": 141,
      "calcium": 110,
      "iron": 0.1,
      "vitamin_a": 4,
      "vitamin_c": 0,
      "vitamin_d": 0
    },
    "serving_sizes": [
      { "description": "1 nádoba (170g)", "grams": 170 },
      { "description": "1 hrnek (245g)", "grams": 245 },
      { "description": "1 lžíce (15g)", "grams": 15 },
      { "description": "100g", "grams": 100 }
    ],
    "allergens": ["mléko"],
    "source": "USDA",
    "source_id": "170903",
    "last_verified": "2026-02-15",
    "confidence_score": 0.98
  }
}

Vyhledávání podle čárového kódu

Vyhledejte potravinový produkt podle jeho čárového kódu.

GET /v1/barcodes/{barcode}

Podporované formáty: UPC-A, UPC-E, EAN-13, EAN-8

Příklad požadavku:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.nutrola.com/v1/barcodes/0049000006346"

Odpověď vrací stejný objekt detailu potraviny jako koncový bod /foods/{food_id}, s dalšími poli specifickými pro čárový kód, jako jsou barcode_format a regional_variants (pole ID potravin pro stejný produkt v různých zemích, které mohou mít odlišné složení).

Analýza receptů

Odešlete seznam ingrediencí a získejte kombinovaný rozpis výživy.

POST /v1/recipes/analyze

Tělo požadavku:

{
  "name": "Ovesné vločky přes noc",
  "servings": 2,
  "ingredients": [
    { "food_id": "food_3k8m2n", "grams": 160 },
    { "food_id": "food_9p4q7r", "grams": 400 },
    { "food_id": "food_1a5b8c", "grams": 60 },
    { "food_id": "food_6d2e9f", "grams": 2, "description": "špetka soli" }
  ]
}

Můžete také odeslat ingredience jako text pro automatické zpracování:

{
  "name": "Ovesné vločky přes noc",
  "servings": 2,
  "ingredients_text": "160g ovesných vloček, 400ml plnotučného mléka, 60g arašídového másla, špetka soli"
}

Odpověď:

{
  "status": "success",
  "data": {
    "name": "Ovesné vločky přes noc",
    "servings": 2,
    "nutrition_per_serving": {
      "calories": 425,
      "protein": 18.5,
      "carbohydrates": 42.3,
      "fat": 21.2,
      "fiber": 5.8
    },
    "nutrition_total": {
      "calories": 850,
      "protein": 37.0,
      "carbohydrates": 84.6,
      "fat": 42.4,
      "fiber": 11.6
    },
    "ingredients_matched": [
      { "input": "160g ovesných vloček", "matched_food": "food_3k8m2n", "confidence": 0.97 },
      { "input": "400ml plnotučného mléka", "matched_food": "food_9p4q7r", "confidence": 0.99 },
      { "input": "60g arašídového másla", "matched_food": "food_1a5b8c", "confidence": 0.96 },
      { "input": "špetka soli", "matched_food": "food_6d2e9f", "confidence": 0.88 }
    ]
  }
}

Automatické doplňování

Rychlé návrhy při psaní pro vytváření vyhledávacích rozhraní.

GET /v1/foods/autocomplete?q={query}

Parametry:

Parametr	Typ	Povinný	Popis
q	string	Ano	Částečný vyhledávací dotaz (minimálně 2 znaky)
limit	integer	Ne	Max. výsledků, 1-10 (výchozí: 5)
country	string	Ne	Prioritizovat výsledky z této země

Časy odpovědí jsou optimalizovány pro interaktivní použití — obvykle pod 50 ms. Koncový bod automatického doplňování vrací zjednodušené objekty potravin (ID, název, značka a kategorie) pro rychlé zobrazení.

Limity rychlosti a ceny

Bezplatný tarif

Bezplatný tarif je navržen pro vývoj, testování a malé aplikace:

Limit	Hodnota
Požadavky za den	500
Požadavky za minutu	30
Výsledky vyhledávání potravin na požadavek	20
Analýza receptů za den	10
Vyhledávání podle čárového kódu za den	100

Růstový tarif

Pro produkční aplikace s mírným provozem:

Limit	Hodnota
Požadavky za den	25,000
Požadavky za minutu	300
Výsledky vyhledávání potravin na požadavek	50
Analýza receptů za den	500
Vyhledávání podle čárového kódu za den	5,000
Cena	$49/měsíc

Podnikový tarif

Pro aplikace s vysokým provozem, řešení s bílou etiketou a vlastní požadavky:

Funkce	Detaily
Požadavky za den	Vlastní (typicky 100K+)
Limity rychlosti	Vlastní
Vyhrazená podpora	Zahrnuta
SLA	Záruka dostupnosti 99.9%
Vlastní exporty dat	K dispozici
Webhook notifikace	K dispozici pro aktualizace dat
Cena	Kontaktujte prodej

Informace o limitech rychlosti jsou zahrnuty v každé odpovědi API prostřednictvím objektu meta a v HTTP hlavičkách odpovědi (X-RateLimit-Remaining, X-RateLimit-Reset).

Příklady použití v reálném světě

Fitness a tréninkové aplikace

Pokud vyvíjíte fitness aplikaci a chcete přidat sledování výživy bez budování databáze potravin od nuly, API Nutrola je nejrychlejší cesta. Použijte koncové body pro vyhledávání potravin a čárové kódy, abyste uživatelům umožnili zaznamenávat jídla, a koncový bod pro analýzu receptů pro vlastní záznamy jídel.

Platformy pro plánování jídel

Aplikace pro plánování jídel potřebují přesné výživové údaje k vytváření plánů, které splňují specifické makro cíle. Podrobný rozpis živin API (70+ živin) umožňuje přesnou optimalizaci plánování jídel, nejen kalorií a makroživin, ale také mikronutrientů, alergenů a kompatibility s dietními omezeními.

Zdravotní péče a telemedicína

Zdravotnické platformy, které monitorují výživu pacientů, mohou integrovat API, aby poskytly přesné sledování potravin v rámci svých stávajících rozhraní. Ověřené zdroje dat (USDA, EFSA, přímo od výrobců) splňují standardy přesnosti potřebné pro klinické monitorování výživy.

Restaurace a stravovací služby

Platformy pro objednávání v restauracích mohou použít API k zobrazení výživových informací pro položky v menu. Konec analýzy receptů je zde obzvlášť užitečný — odešlete ingredience pokrmu a získejte kompletní rozpis výživy bez manuálního výpočtu každé položky.

Výzkum a akademie

Výzkumníci v oblasti výživy mohou použít API k standardizaci kódování potravin v dietních studiích. Konzistentní, ověřená data snižují chybovost měření, která sužuje studie spoléhající se na údaje o výživě hlášené účastníky.

Příklady kódu

Python: Vyhledání potraviny a získání detailů o výživě

import requests

API_KEY = "ntr_live_your_key_here"
BASE_URL = "https://api.nutrola.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

# Vyhledání potraviny
search_response = requests.get(
    f"{BASE_URL}/foods/search",
    headers=headers,
    params={"q": "grilované kuřecí prso", "per_page": 3}
)

results = search_response.json()["data"]["results"]

for food in results:
    print(f"{food['name']} - {food['nutrition_per_100g']['calories']} kal/100g")

# Získání plných detailů pro první výsledek
food_id = results[0]["id"]
detail_response = requests.get(
    f"{BASE_URL}/foods/{food_id}",
    headers=headers
)

food_detail = detail_response.json()["data"]
nutrition = food_detail["nutrition_per_100g"]

print(f"\n{food_detail['name']}")
print(f"Kalorie: {nutrition['calories']}")
print(f"Bílkoviny: {nutrition['protein']}g")
print(f"Sacharidy: {nutrition['carbohydrates']}g")
print(f"Tuky: {nutrition['fat']}g")
print(f"Velikosti porcí: {food_detail['serving_sizes']}")

JavaScript: Integrace skenování čárového kódu

const API_KEY = "ntr_live_your_key_here";
const BASE_URL = "https://api.nutrola.com/v1";

async function lookupBarcode(barcode) {
  const response = await fetch(
    `${BASE_URL}/barcodes/${barcode}`,
    {
      headers: {
        "Authorization": `Bearer ${API_KEY}`
      }
    }
  );

  if (!response.ok) {
    if (response.status === 404) {
      console.log("Produkt nebyl nalezen v databázi");
      return null;
    }
    throw new Error(`Chyba API: ${response.status}`);
  }

  const data = await response.json();
  return data.data;
}

// Příklad použití
const product = await lookupBarcode("0049000006346");

if (product) {
  const serving = product.default_serving;
  const factor = serving.grams / 100;

  console.log(`${product.name} (${product.brand})`);
  console.log(`Na ${serving.description}:`);
  console.log(`  Kalorie: ${Math.round(product.nutrition_per_100g.calories * factor)}`);
  console.log(`  Bílkoviny: ${(product.nutrition_per_100g.protein * factor).toFixed(1)}g`);
  console.log(`  Sacharidy: ${(product.nutrition_per_100g.carbohydrates * factor).toFixed(1)}g`);
  console.log(`  Tuky: ${(product.nutrition_per_100g.fat * factor).toFixed(1)}g`);
}

Swift: Vytváření pole pro automatické doplňování

import Foundation

class Nutrola API {
    private let apiKey: String
    private let baseURL = "https://api.nutrola.com/v1"

    init(apiKey: String) {
        self.apiKey = apiKey
    }

    func autocomplete(query: String, limit: Int = 5) async throws -> [FoodSuggestion] {
        guard query.count >= 2 else { return [] }

        var components = URLComponents(string: "\(baseURL)/foods/autocomplete")!
        components.queryItems = [
            URLQueryItem(name: "q", value: query),
            URLQueryItem(name: "limit", value: String(limit))
        ]

        var request = URLRequest(url: components.url!)
        request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")

        let (data, _) = try await URLSession.shared.data(for: request)
        let response = try JSONDecoder().decode(AutocompleteResponse.self, from: data)
        return response.data.suggestions
    }
}

struct FoodSuggestion: Codable {
    let id: String
    let name: String
    let brand: String?
    let category: String
}

struct AutocompleteResponse: Codable {
    let status: String
    let data: AutocompleteData
}

struct AutocompleteData: Codable {
    let suggestions: [FoodSuggestion]
}

Nejlepší postupy pro zpracování chyb

API používá standardní HTTP stavové kódy:

Stavový kód	Význam	Běžná příčina
200	Úspěch	Požadavek byl úspěšně dokončen
400	Chybný požadavek	Chybí povinný parametr nebo neplatná hodnota
401	Neautorizováno	Neplatný nebo chybějící API klíč
403	Zakázáno	API klíč nemá požadovaný rozsah
404	Nenalezeno	ID potraviny nebo čárový kód není v databázi
429	Omezena rychlost	Příliš mnoho požadavků; zkontrolujte hlavičky limitu rychlosti
500	Chyba serveru	Interní chyba; zkuste to znovu s exponenciálním zpětným zpožděním

Když obdržíte odpověď 429, hlavička Retry-After vám říká, jak dlouho čekat před opětovným pokusem. Implementace exponenciálního zpětného zpoždění pro odpovědi 429 a 500 je pro produkční aplikace důrazně doporučena.

Čerstvost dat a aktualizace

Databáze Nutrola je neustále aktualizována. Záznamy o značkových produktech jsou obnoveny, když výrobci hlásí změny, obvykle do 48 hodin. Záznamy z vládních databází jsou synchronizovány čtvrtletně, když jsou zveřejněny nové verze.

Pokud vaše aplikace ukládá odpovědi API do mezipaměti (což doporučujeme pro výkon), doporučujeme TTL mezipaměti 24 hodin pro odpovědi detailů potravin a 1 hodinu pro výsledky vyhledávání. Pole last_verified v odpovědích detailů potravin vám říká, kdy byl záznam naposledy potvrzen jako přesný.

Pro podnikové zákazníky nabízíme webhook notifikace, když jsou záznamy potravin aktualizovány, takže vaše aplikace může proaktivně zneplatnit mezipaměť, místo aby čekala na vypršení TTL mezipaměti.

Jak začít

1. Zaregistrujte se na developer.nutrola.com — zabere to méně než minutu
2. Vygenerujte API klíč s požadovanými rozsahy
3. Proveďte svůj první požadavek pomocí výše uvedených příkladů curl
4. Prozkoumejte interaktivní dokumentaci na developer.nutrola.com/docs, kde můžete testovat koncové body přímo ve svém prohlížeči
5. Připojte se k vývojářské komunitě na našem Discord serveru pro podporu, žádosti o funkce a pro zjištění, co ostatní vývojáři vytvářejí

Pokud máte dotazy, narazíte na problémy nebo chcete diskutovat o podnikové integraci, obraťte se na náš tým pro vztahy s vývojáři na api@nutrola.com.

Často kladené otázky

Je Nutrola API zdarma k použití?

Ano, existuje bezplatný tarif, který zahrnuje 500 požadavků za den. To je vhodné pro vývoj, testování a malé aplikace. Pro produkční aplikace s vyšším provozem začíná růstový tarif na 49 $ měsíčně s 25 000 denními požadavky. Podnikové plány s vlastními limity jsou k dispozici pro případy s vysokým provozem.

Jaké formáty dat API podporuje?

API používá výhradně JSON pro požadavky i odpovědi. Všechny koncové body přijímají standardní dotazové parametry pro GET požadavky a JSON těla požadavků pro POST požadavky. Kódování odpovědí je UTF-8, což správně zpracovává názvy potravin ve všech podporovaných jazycích.

Jak přesná jsou výživová data poskytovaná API?

Každý záznam v databázi Nutrola prochází vícestupňovým ověřovacím procesem, včetně validace vládních zdrojů, křížového ověřování dat od výrobců, statistického ověřování pomocí AI a revizí lidských expertů. Naše přesnost je 97,4 % ve srovnání s laboratorní analýzou, zatímco průměr v oboru je 70-85 % pro databáze založené na crowdsourcingu. Každý záznam potraviny obsahuje pole confidence_score, které udává naši úroveň jistoty.

Mohu API použít k vytvoření komerčního produktu?

Ano. API je navrženo pro komerční použití. Bezplatný tarif může být použit pro komerční produkty v rámci svých limitů. Růstové a podnikové plány zahrnují práva na komerční použití bez omezení na typ aplikace. Podívejte se na podmínky služby na developer.nutrola.com pro podrobnosti.

Podporuje API potraviny z mimo Spojené státy?

Ano. Databáze pokrývá značkové produkty z 47 zemí a generické potraviny z více než 120 kuchyní. Použijte parametr country na vyhledávacích koncových bodech pro prioritizaci výsledků z konkrétního trhu. Vyhledávání podle čárového kódu automaticky přiřazuje produkt k správnému regionálnímu složení.

Jak mám zacházet s potravinami, které nejsou v databázi?

Pokud vyhledávání podle čárového kódu vrátí 404, můžete přejít na textové vyhledávání pomocí názvu produktu. Pokud ani jeden přístup nenajde potravinu, můžete ji navrhnout k přidání prostřednictvím vývojářského portálu. Potraviny navržené partnery API jsou prioritizovány pro ověření a obvykle jsou přidány do 72 hodin. Podnikové zákazníky mohou požádat o hromadné přidání pro velké katalogy produktů.

Jsou k dispozici SDK nebo klientské knihovny?

Poskytujeme oficiální klientské knihovny pro Python (přes pip: pip install nutrola), JavaScript/TypeScript (přes npm: npm install @nutrola/api) a Swift (přes Swift Package Manager). Tyto knihovny se starají o autentizaci, limity rychlosti, opakování a analýzu odpovědí. Komunitou udržované knihovny jsou k dispozici pro Go, Ruby a PHP.