API-ul de Date Nutriționale Nutrola: Cum pot Accesa Dezvoltatorii Baza Noastră de Date Alimentare

Construiești o aplicație de sănătate, fitness sau alimentație? Una dintre cele mai mari provocări cu care te vei confrunta este obținerea datelor nutriționale. Ai nevoie de informații precise despre calorii și macronutrienți pentru mii de alimente, trebuie să acoperi produse internaționale și să te asiguri că informațiile sunt actualizate, pe măsură ce producătorii își reformulează produsele.

Majoritatea dezvoltatorilor încep prin a extrage date din baze de date guvernamentale deschise, cum ar fi USDA FoodData Central. Aceasta îți oferă o bază de pornire, dar nu acoperă produsele de marcă din 47 de țări, mesele din restaurante sau miile de alimente regionale pe care utilizatorii le consumă zilnic. Umplerea acestor goluri pe cont propriu înseamnă ani de muncă de curare a datelor.

API-ul de Date Nutriționale Nutrola oferă dezvoltatorilor acces la aceeași bază de date alimentare verificate care stă la baza aplicației noastre — peste 3 milioane de intrări, acoperind ingrediente brute, produse de marcă, mese din restaurante și rețete compuse. Fiecare intrare este verificată prin procesul nostru de control al calității în mai multe etape, același sistem de care se bucură peste 2 milioane de utilizatori.

Acest ghid acoperă tot ce trebuie să știi pentru a începe să construiești cu API-ul nostru: arhitectură, autentificare, endpoint-uri, limite de rată și exemple de cod din viața reală.

Prezentare API

API-ul de Date Nutriționale Nutrola este un API RESTful JSON. Efectuezi cereri HTTP și primești răspunsuri JSON. Nu sunt necesare SDK-uri, deși oferim biblioteci client pentru Python, JavaScript și Swift pentru comoditate.

URL de bază

https://api.nutrola.com/v1

Toate endpoint-urile sunt servite prin HTTPS. Cererile HTTP simple sunt respinse.

Capacități Cheie

Capacitate	Descriere
Căutare Alimente	Căutare text complet în peste 3M de intrări alimentare, cu filtrare după categorie, marcă și țară
Căutare după Cod de Bare	Obține date nutriționale după UPC, EAN sau alte formate de coduri de bare
Detalii Nutriționale	Profil nutrițional complet pentru orice aliment (peste 70 de nutrienți, inclusiv micronutrienți)
Dimensiuni de Porție	Dimensiuni standard și alternative de porție, cu conversii în grame
Analiza Rețetelor	Trimite o listă de ingrediente și obține date nutriționale combinate
Categorii de Alimente	Răsfoiește taxonomia ierarhică a categoriilor alimentare
Director de Mărci	Caută și răsfoiește producătorii de alimente de marcă
Autocompletare	Sugestii rapide pentru căutările alimentelor

Formatul Răspunsului

Toate răspunsurile urmează o structură consistentă:

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

Răspunsurile de eroare includ un cod de eroare citibil de mașină și un mesaj ușor de înțeles:

{
  "status": "error",
  "error": {
    "code": "FOOD_NOT_FOUND",
    "message": "Nicio intrare alimentară nu se potrivește cu ID-ul furnizat.",
    "request_id": "req_xyz789"
  }
}

Autentificare

Toate cererile API necesită o cheie API trecută în antetul Authorization.

Obținerea unei Chei API

1. Creează un cont de dezvoltator la developer.nutrola.com
2. Navighează la secțiunea Chei API din tabloul tău de bord
3. Generează o cheie nouă și specifică domeniile de acces de care ai nevoie
4. Stochează cheia în siguranță — va fi afișată o singură dată

Utilizarea Cheii Tale API

Include cheia în fiecare antet de cerere:

Authorization: Bearer YOUR_API_KEY

Exemplu cu curl:

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

Domeniile Cheii API

Domeniu	Nivel de Acces
foods:read	Căutare și recuperare date alimentare (cel mai comun)
barcodes:read	Căutare după cod de bare
recipes:analyze	Analiza nutrițională a rețetelor
brands:read	Acces la directorul de mărci
categories:read	Taxonomia categoriilor alimentare

Cheile pot fi limitate la capacități specifice. O cheie cu doar foods:read nu poate accesa căutările după coduri de bare. Aceasta urmează principiul minimului privilegiu — solicită doar domeniile de care are nevoie aplicația ta.

Endpoint-uri de Bază

Căutare Alimente

Caută în baza de date după nume, cuvânt cheie sau frază.

GET /v1/foods/search

Parametrii:

Parametru	Tip	Necesare	Descriere
q	string	Da	Interogare de căutare (ex: "piept de pui la grătar")
category	string	Nu	Filtrare după categorie alimentară (ex: "lactate", "legume")
brand	string	Nu	Filtrare după numele mărcii
country	string	Nu	Codul de țară ISO 3166-1 alpha-2 (ex: "US", "DE", "JP")
verified_only	boolean	Nu	Returnează doar intrările cu date de sursă verificate (implicit: adevărat)
page	integer	Nu	Numărul paginii pentru paginare (implicit: 1)
per_page	integer	Nu	Rezultate pe pagină, maxim 50 (implicit: 20)

Exemplu de Cerere:

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

Exemplu de Răspuns:

{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "food_8f2k9d",
        "name": "Iaurt Grecesc, Simplu, Fără Grăsime",
        "brand": null,
        "category": "dairy",
        "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 recipient (170g)",
          "grams": 170
        }
      }
    ],
    "total_results": 342,
    "page": 1,
    "per_page": 5
  }
}

Obține Detalii despre Alimente

Recuperați profilul nutrițional complet pentru un aliment specific.

GET /v1/foods/{food_id}

Exemplu de Cerere:

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

Răspunsul detaliat include întreaga descompunere a nutrienților — peste 70 de nutrienți, inclusiv toate vitaminele, mineralele, aminoacizii și profilele acizilor grași. De asemenea, include toate dimensiunile de porție disponibile și echivalentele lor în grame.

Răspuns Parțial (Nutrienți Cheie):

{
  "status": "success",
  "data": {
    "id": "food_8f2k9d",
    "name": "Iaurt Grecesc, Simplu, Fără Grăsime",
    "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 recipient (170g)", "grams": 170 },
      { "description": "1 cană (245g)", "grams": 245 },
      { "description": "1 lingură (15g)", "grams": 15 },
      { "description": "100g", "grams": 100 }
    ],
    "allergens": ["lapte"],
    "source": "USDA",
    "source_id": "170903",
    "last_verified": "2026-02-15",
    "confidence_score": 0.98
  }
}

Căutare după Cod de Bare

Caută un produs alimentar după codul său de bare.

GET /v1/barcodes/{barcode}

Formate Acceptate: UPC-A, UPC-E, EAN-13, EAN-8

Exemplu de Cerere:

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

Răspunsul returnează același obiect de detaliu alimentar ca endpoint-ul /foods/{food_id}, cu câmpuri suplimentare specifice codului de bare, cum ar fi barcode_format și regional_variants (un array de ID-uri alimentare pentru același produs în diferite țări, care pot avea formulări diferite).

Analiza Rețetelor

Trimite o listă de ingrediente și primește descompunerea nutrițională combinată.

POST /v1/recipes/analyze

Corpul Cererii:

{
  "name": "Ovăz peste Noapte",
  "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": "un vârf de sare" }
  ]
}

Poți, de asemenea, să trimiți ingredientele ca text pentru analiză automată:

{
  "name": "Ovăz peste Noapte",
  "servings": 2,
  "ingredients_text": "160g ovăz, 400ml lapte integral, 60g unt de arahide, un vârf de sare"
}

Răspuns:

{
  "status": "success",
  "data": {
    "name": "Ovăz peste Noapte",
    "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 ovăz", "matched_food": "food_3k8m2n", "confidence": 0.97 },
      { "input": "400ml lapte integral", "matched_food": "food_9p4q7r", "confidence": 0.99 },
      { "input": "60g unt de arahide", "matched_food": "food_1a5b8c", "confidence": 0.96 },
      { "input": "un vârf de sare", "matched_food": "food_6d2e9f", "confidence": 0.88 }
    ]
  }
}

Autocompletare

Sugestii rapide pentru construirea interfețelor de căutare.

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

Parametrii:

Parametru	Tip	Necesare	Descriere
q	string	Da	Interogare parțială de căutare (minim 2 caractere)
limit	integer	Nu	Max rezultate, 1-10 (implicit: 5)
country	string	Nu	Prioritizează rezultatele din această țară

Timpul de răspuns este optimizat pentru utilizare interactivă — de obicei sub 50ms. Endpoint-ul de autocompletare returnează obiecte alimentare simplificate (ID, nume, marcă și categorie) pentru redare rapidă.

Limite de Rată și Prețuri

Nivel Gratuit

Nivelul gratuit este conceput pentru dezvoltare, testare și aplicații de mică amploare:

Limită	Valoare
Cereri pe zi	500
Cereri pe minut	30
Rezultate căutare alimente pe cerere	20
Analiza rețetelor pe zi	10
Căutări după cod de bare pe zi	100

Nivel de Creștere

Pentru aplicații de producție cu trafic moderat:

Limită	Valoare
Cereri pe zi	25,000
Cereri pe minut	300
Rezultate căutare alimente pe cerere	50
Analiza rețetelor pe zi	500
Căutări după cod de bare pe zi	5,000
Preț	$49/lună

Nivel Enterprise

Pentru aplicații cu trafic ridicat, soluții white-label și cerințe personalizate:

Caracteristică	Detalii
Cereri pe zi	Personalizat (de obicei 100K+)
Limite de rată	Personalizate
Suport dedicat	Inclus
SLA	99.9% garanție de uptime
Exports de date personalizate	Disponibile
Notificări webhook	Disponibile pentru actualizări de date
Preț	Contactează vânzările

Informațiile despre limitele de rată sunt incluse în fiecare răspuns API prin obiectul meta și în anteturile de răspuns HTTP (X-RateLimit-Remaining, X-RateLimit-Reset).

Cazuri de Utilizare din Viața Reală

Aplicații de Fitness și Antrenament

Dacă construiești o aplicație de fitness și vrei să adaugi urmărirea nutriției fără a construi o bază de date alimentară de la zero, API-ul Nutrola este cea mai rapidă cale. Folosește endpoint-urile de căutare a alimentelor și coduri de bare pentru a permite utilizatorilor să înregistreze mese, iar endpoint-ul de analiză a rețetelor pentru intrări personalizate.

Platforme de Planificare a Meselor

Aplicațiile de planificare a meselor au nevoie de date nutriționale precise pentru a genera planuri care să atingă obiective specifice de macronutrienți. Descompunerea detaliată a nutrienților API-ului (peste 70 de nutrienți) permite optimizarea precisă a planurilor de mese, nu doar calorii și macronutrienți, ci și micronutrienți, alergeni și compatibilitate cu restricțiile dietetice.

Sănătate și Telemedicină

Platformele de sănătate care monitorizează nutriția pacienților pot integra API-ul pentru a oferi înregistrări alimentare precise în cadrul interfețelor existente. Sursele de date verificate (USDA, EFSA, direct de la producători) respectă standardele de acuratețe necesare pentru monitorizarea nutriției clinice.

Restaurante și Servicii Alimentare

Platformele de comandă din restaurante pot folosi API-ul pentru a afișa informații nutriționale pentru articolele din meniu. Endpoint-ul de analiză a rețetelor este deosebit de util aici — trimite ingredientele unui fel de mâncare și obține descompunerea nutrițională completă fără a calcula manual fiecare element.

Cercetare și Academia

Cercetătorii în nutriție pot folosi API-ul pentru a standardiza codificarea alimentelor în studiile dietetice. Datele consistente și verificate reduc eroarea de măsurare care afectează studiile bazate pe datele raportate de participanți.

Exemple de Cod

Python: Caută un Aliment și Obține Detalii Nutriționale

import requests

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

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

# Caută un aliment
search_response = requests.get(
    f"{BASE_URL}/foods/search",
    headers=headers,
    params={"q": "piept de pui la grătar", "per_page": 3}
)

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

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

# Obține detalii complete pentru primul rezultat
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"Calorii: {nutrition['calories']}")
print(f"Proteine: {nutrition['protein']}g")
print(f"Carbohidrați: {nutrition['carbohydrates']}g")
print(f"Grăsimi: {nutrition['fat']}g")
print(f"Dimensiuni de porție: {food_detail['serving_sizes']}")

JavaScript: Integrarea Scanării Codului de Bare

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("Produsul nu a fost găsit în baza de date");
      return null;
    }
    throw new Error(`Eroare API: ${response.status}`);
  }

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

// Exemplu de utilizare
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(`Pe ${serving.description}:`);
  console.log(`  Calorii: ${Math.round(product.nutrition_per_100g.calories * factor)}`);
  console.log(`  Proteine: ${(product.nutrition_per_100g.protein * factor).toFixed(1)}g`);
  console.log(`  Carbohidrați: ${(product.nutrition_per_100g.carbohydrates * factor).toFixed(1)}g`);
  console.log(`  Grăsimi: ${(product.nutrition_per_100g.fat * factor).toFixed(1)}g`);
}

Swift: Construirea unui Câmp de Căutare Autocompletare

import Foundation

class NutrolaAPI {
    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]
}

Cele Mai Bune Practici pentru Gestionarea Erorilor

API-ul folosește coduri de stare HTTP standard:

Cod de Stare	Semnificație	Cauză Comună
200	Succes	Cererea a fost finalizată normal
400	Cerere Greșită	Parametru necesar lipsă sau valoare invalidă
401	Neautorizat	Cheie API invalidă sau lipsă
403	Interzis	Cheia API nu are domeniul necesar
404	Nu a fost Găsit	ID-ul alimentului sau codul de bare nu se află în baza de date
429	Limită de Rată	Prea multe cereri; verifică anteturile limitelor de rată
500	Eroare de Server	Eroare internă; încearcă din nou cu un backoff exponențial

Când primești un răspuns 429, antetul Retry-After îți spune câte secunde să aștepți înainte de a încerca din nou. Implementarea backoff-ului exponențial pentru răspunsurile 429 și 500 este puternic recomandată pentru aplicațiile de producție.

Actualizarea și Prospetimea Datelor

Baza de date Nutrola este actualizată continuu. Intrările pentru produsele de marcă sunt reîmprospătate atunci când producătorii raportează modificări, de obicei în termen de 48 de ore. Intrările din baza de date guvernamentală sunt sincronizate trimestrial, când sunt publicate noi versiuni.

Dacă aplicația ta stochează în cache răspunsurile API (ceea ce recomandăm pentru performanță), sugerăm un TTL de cache de 24 de ore pentru răspunsurile detaliate despre alimente și 1 oră pentru rezultatele căutării. Câmpul last_verified din răspunsurile detaliate despre alimente îți spune când a fost confirmată ultima dată acuratețea intrării.

Pentru clienții enterprise, oferim notificări webhook atunci când intrările alimentare sunt actualizate, astfel încât aplicația ta să poată invalida datele stocate în cache proactiv, fără a aștepta expirarea TTL-ului cache-ului.

Începe

1. Înscrie-te la developer.nutrola.com — durează mai puțin de un minut
2. Generează o cheie API cu domeniile de acces de care ai nevoie
3. Fă prima ta cerere folosind exemplele curl de mai sus
4. Explorează documentația interactivă la developer.nutrola.com/docs unde poți testa endpoint-urile direct în browser
5. Alătură-te comunității de dezvoltatori pe serverul nostru Discord pentru suport, cereri de funcții și pentru a vedea ce construiesc alți dezvoltatori

Dacă ai întrebări, întâmpini probleme sau vrei să discuți despre o integrare enterprise, contactează echipa noastră de relații cu dezvoltatorii la api@nutrola.com.

Întrebări Frecvente

Este API-ul Nutrola gratuit de utilizat?

Da, există un nivel gratuit care include 500 de cereri pe zi. Acesta este potrivit pentru dezvoltare, testare și aplicații de mică amploare. Pentru aplicațiile de producție cu trafic mai mare, nivelul de Creștere începe de la 49 USD pe lună cu 25.000 de cereri zilnice. Planurile Enterprise cu limite personalizate sunt disponibile pentru cazuri de utilizare cu trafic ridicat.

Ce formate de date acceptă API-ul?

API-ul folosește exclusiv JSON pentru cereri și răspunsuri. Toate endpoint-urile acceptă parametrii standard de interogare pentru cererile GET și corpuri de cerere JSON pentru cererile POST. Codificarea răspunsurilor este UTF-8, care gestionează corect numele alimentelor în toate limbile acceptate.

Cât de precise sunt datele nutriționale furnizate de API?

Fiecare intrare din baza de date Nutrola trece printr-un proces de verificare în mai multe etape, inclusiv validarea surselor guvernamentale, corelarea datelor de la producători, verificarea statistică asistată de AI și revizuirea de către experți umani. Standardul nostru de acuratețe este de 97,4% comparativ cu analiza de laborator, în comparație cu o medie a industriei de 70-85% pentru bazele de date crowdsourced. Fiecare intrare alimentară include un câmp confidence_score care indică nivelul nostru de certitudine.

Pot folosi API-ul pentru a construi un produs comercial?

Da. API-ul este conceput pentru utilizare comercială. Nivelul gratuit poate fi utilizat pentru produse comerciale în limitele sale de rată. Planurile de Creștere și Enterprise includ drepturi de utilizare comercială fără restricții asupra tipului de aplicație. Consultă termenii de serviciu la developer.nutrola.com pentru detalii complete.

Susține API-ul alimente din afara Statelor Unite?

Da. Baza de date acoperă produse de marcă din 47 de țări și alimente generice din peste 120 de bucătării. Folosește parametrul country pe endpoint-urile de căutare pentru a prioritiza rezultatele dintr-o piață specifică. Căutările după coduri de bare se potrivesc automat produsului cu formularea regională corectă.

Cum gestionez alimentele care nu se află în baza de date?

Dacă o căutare după cod de bare returnează un 404, poți recurge la o căutare text folosind numele produsului. Dacă nici o abordare nu găsește alimentul, poți să-l trimiți pentru adăugare prin portalul dezvoltatorilor. Alimentele trimise de partenerii API sunt prioritizate pentru verificare și, de obicei, sunt adăugate în termen de 72 de ore. Clienții Enterprise pot solicita adăugări în loturi pentru cataloage mari de produse.

Există SDK-uri sau biblioteci client disponibile?

Oferim biblioteci client oficiale pentru Python (prin pip: pip install nutrola), JavaScript/TypeScript (prin npm: npm install @nutrola/api) și Swift (prin Swift Package Manager). Aceste biblioteci gestionează autentificarea, limitarea ratelor, retry-urile și analiza răspunsurilor. Biblioteci întreținute de comunitate sunt disponibile pentru Go, Ruby și PHP.