Nutrola Besin Verisi API'si: Geliştiricilerin Gıda Veritabanımıza Erişimi

Sağlık, fitness veya gıda ile ilgili bir uygulama mı geliştiriyorsunuz? Karşılaşacağınız en büyük sorunlardan biri besin verisi. Binlerce gıda için doğru kalori ve makro bilgilerine ihtiyacınız var, uluslararası ürünleri kapsaması gerekiyor ve üreticiler ürünlerini yeniden formüle ettikçe güncel kalması şart.

Çoğu geliştirici, USDA FoodData Central gibi açık devlet veritabanlarından veri çekerek başlar. Bu, bir temel sağlar, ancak 47 ülkeden markalı ürünleri, restoran yemeklerini veya gerçek kullanıcıların her gün tükettiği binlerce yerel gıdayı kapsamaz. Bu boşlukları kendiniz doldurmak, yıllarca süren veri derleme çalışması anlamına gelir.

Nutrola'nın Besin Verisi API'si, geliştiricilere uygulamamızı destekleyen aynı doğrulanmış gıda veritabanına erişim sunar — 3 milyondan fazla kayıt, ham maddeler, markalı ürünler, restoran yemekleri ve bileşik tarifleri kapsar. Her kayıt, 2 milyondan fazla kullanıcı tarafından güvenilen çok katmanlı kalite kontrol sürecimizle doğrulanmıştır.

Bu kılavuz, API'mizle çalışmaya başlamak için bilmeniz gereken her şeyi kapsar: mimari, kimlik doğrulama, uç noktalar, hız sınırları ve gerçek dünya kod örnekleri.

API Genel Bakış

Nutrola Besin Verisi API'si, RESTful JSON API'sidir. HTTP istekleri yaparsınız, JSON yanıtları alırsınız. SDK'lara gerek yoktur, ancak Python, JavaScript ve Swift için kolaylık sağlamak amacıyla istemci kütüphaneleri sunuyoruz.

Temel URL

https://api.nutrola.com/v1

Tüm uç noktalar HTTPS üzerinden sunulmaktadır. Düz HTTP istekleri reddedilir.

Ana Özellikler

Özellik	Açıklama
Gıda Arama	3M+ gıda kaydı arasında tam metin arama, kategori, marka ve ülkeye göre filtreleme
Barkod Arama	UPC, EAN veya diğer barkod formatlarıyla besin verisi alma
Besin Detayları	Herhangi bir gıda için tam besin profili (70+ besin maddesi dahil)
Porsiyon Boyutları	Gram dönüşümleri ile standart ve alternatif porsiyon boyutları
Tarif Analizi	Bir malzeme listesi gönderin ve birleştirilmiş besin verisi alın
Gıda Kategorileri	Hiyerarşik gıda kategori taksonomisini gözden geçirin
Marka Dizini	Markalı gıda üreticilerini arayın ve gözden geçirin
Otomatik Tamamlama	Gıda arama arayüzleri için hızlı öneriler

Yanıt Formatı

Tüm yanıtlar tutarlı bir yapıyı takip eder:

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

Hata yanıtları, makine tarafından okunabilir bir hata kodu ve insan tarafından okunabilir bir mesaj içerir:

{
  "status": "error",
  "error": {
    "code": "FOOD_NOT_FOUND",
    "message": "Verilen ID ile eşleşen bir gıda kaydı bulunamadı.",
    "request_id": "req_xyz789"
  }
}

Kimlik Doğrulama

Tüm API istekleri, Authorization başlığında bir API anahtarı gerektirir.

API Anahtarı Alma

1. developer.nutrola.com adresinde bir geliştirici hesabı oluşturun
2. Kontrol panelinizde API Anahtarları bölümüne gidin
3. Yeni bir anahtar oluşturun ve ihtiyaç duyduğunuz kapsamları belirtin
4. Anahtarı güvenli bir yerde saklayın — yalnızca bir kez görüntülenecektir

API Anahtarınızı Kullanma

Her isteğin başlığına anahtarı ekleyin:

Authorization: Bearer YOUR_API_KEY

Curl ile örnek:

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

API Anahtarı Kapsamları

Kapsam	Erişim Seviyesi
foods:read	Gıda verilerini arama ve alma (en yaygın)
barcodes:read	Barkod arama
recipes:analyze	Tarif besin analizi
brands:read	Marka dizini erişimi
categories:read	Gıda kategori taksonomisi

Anahtarlar, belirli yeteneklere göre kapsamlanabilir. Sadece foods:read olan bir anahtar, barkod aramalarına erişemez. Bu, en az ayrıcalık ilkesine uygundur — uygulamanızın ihtiyaç duyduğu kapsamları yalnızca talep edin.

Temel Uç Noktalar

Gıda Arama

Veritabanında isim, anahtar kelime veya ifade ile arama yapın.

GET /v1/foods/search

Parametreler:

Parametre	Tür	Gerekli	Açıklama
q	string	Evet	Arama sorgusu (örn. "ızgara tavuk göğsü")
category	string	Hayır	Gıda kategorisine göre filtreleme (örn. "süt ürünleri", "sebzeler")
brand	string	Hayır	Marka adına göre filtreleme
country	string	Hayır	ISO 3166-1 alpha-2 ülke kodu (örn. "US", "DE", "JP")
verified_only	boolean	Hayır	Yalnızca doğrulanmış kaynak verileri olan kayıtları döndür (varsayılan: true)
page	integer	Hayır	Sayfalama için sayfa numarası (varsayılan: 1)
per_page	integer	Hayır	Sayfa başına sonuç sayısı, maksimum 50 (varsayılan: 20)

Örnek İstek:

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

Örnek Yanıt:

{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "food_8f2k9d",
        "name": "Yunan Yoğurdu, Sade, Yağsız",
        "brand": null,
        "category": "süt ürünleri",
        "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 kap (170g)",
          "grams": 170
        }
      }
    ],
    "total_results": 342,
    "page": 1,
    "per_page": 5
  }
}

Gıda Detaylarını Alma

Belirli bir gıda için tam besin profilini alın.

GET /v1/foods/{food_id}

Örnek İstek:

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

Detay yanıtı, 70'ten fazla besin maddesi dahil olmak üzere tam besin içeriğini içerir. Ayrıca, mevcut tüm porsiyon boyutlarını ve gram eşdeğerlerini de içerir.

Kısmi Yanıt (Ana Besinler):

{
  "status": "success",
  "data": {
    "id": "food_8f2k9d",
    "name": "Yunan Yoğurdu, Sade, Yağsız",
    "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 kap (170g)", "grams": 170 },
      { "description": "1 su bardağı (245g)", "grams": 245 },
      { "description": "1 yemek kaşığı (15g)", "grams": 15 },
      { "description": "100g", "grams": 100 }
    ],
    "allergens": ["süt"],
    "source": "USDA",
    "source_id": "170903",
    "last_verified": "2026-02-15",
    "confidence_score": 0.98
  }
}

Barkod Arama

Bir gıda ürününü barkodu ile arayın.

GET /v1/barcodes/{barcode}

Desteklenen Formatlar: UPC-A, UPC-E, EAN-13, EAN-8

Örnek İstek:

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

Yanıt, /foods/{food_id} uç noktasındaki aynı gıda detay nesnesini döndürür; ek olarak barcode_format ve regional_variants gibi barkoda özgü alanlar içerir (farklı ülkelerde aynı ürün için farklı formülasyonlar içerebilecek gıda ID'lerinin bir dizisi).

Tarif Analizi

Bir malzeme listesi gönderin ve birleştirilmiş besin içeriğini alın.

POST /v1/recipes/analyze

İstek Gövdesi:

{
  "name": "Gece Yulafı",
  "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": "bir tutam tuz" }
  ]
}

Ayrıca, malzemeleri otomatik olarak ayrıştırmak için metin olarak da gönderebilirsiniz:

{
  "name": "Gece Yulafı",
  "servings": 2,
  "ingredients_text": "160g yulaf ezmesi, 400ml tam süt, 60g fıstık ezmesi, bir tutam tuz"
}

Yanıt:

{
  "status": "success",
  "data": {
    "name": "Gece Yulafı",
    "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 yulaf ezmesi", "matched_food": "food_3k8m2n", "confidence": 0.97 },
      { "input": "400ml tam süt", "matched_food": "food_9p4q7r", "confidence": 0.99 },
      { "input": "60g fıstık ezmesi", "matched_food": "food_1a5b8c", "confidence": 0.96 },
      { "input": "bir tutam tuz", "matched_food": "food_6d2e9f", "confidence": 0.88 }
    ]
  }
}

Otomatik Tamamlama

Arama arayüzleri oluşturmak için hızlı öneriler.

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

Parametreler:

Parametre	Tür	Gerekli	Açıklama
q	string	Evet	Kısmi arama sorgusu (minimum 2 karakter)
limit	integer	Hayır	Maksimum sonuç, 1-10 (varsayılan: 5)
country	string	Hayır	Bu ülkeden sonuçları önceliklendirin

Yanıt süreleri etkileşimli kullanım için optimize edilmiştir — genellikle 50ms altında. Otomatik tamamlama uç noktası, hızlı render için basitleştirilmiş gıda nesneleri (ID, isim, marka ve kategori yalnızca) döndürür.

Hız Sınırları ve Fiyatlandırma

Ücretsiz Katman

Ücretsiz katman, geliştirme, test etme ve küçük ölçekli uygulamalar için tasarlanmıştır:

Limit	Değer
Günlük istek sayısı	500
Dakikada istek sayısı	30
İstek başına gıda arama sonuçları	20
Günlük tarif analizi	10
Günlük barkod arama	100

Büyüme Katmanı

Orta düzey trafik için üretim uygulamaları:

Limit	Değer
Günlük istek sayısı	25,000
Dakikada istek sayısı	300
İstek başına gıda arama sonuçları	50
Günlük tarif analizi	500
Günlük barkod arama	5,000
Fiyat	$49/ay

Kurumsal Katman

Yüksek trafik uygulamaları, beyaz etiket çözümleri ve özel gereksinimler için:

Özellik	Detaylar
Günlük istek sayısı	Özel (genellikle 100K+)
Hız sınırları	Özel
Özel destek	Dahil
SLA	%99.9 çalışma süresi garantisi
Özel veri dışa aktarımları	Mevcut
Webhook bildirimleri	Veri güncellemeleri için mevcut
Fiyat	Satış ile iletişime geçin

Hız sınırı bilgileri, her API yanıtında meta nesnesi aracılığıyla ve HTTP yanıt başlıklarında (X-RateLimit-Remaining, X-RateLimit-Reset) yer almaktadır.

Gerçek Dünya Kullanım Senaryoları

Fitness ve Egzersiz Uygulamaları

Bir fitness uygulaması geliştiriyorsanız ve besin takibi eklemek istiyorsanız, Nutrola'nın API'si en hızlı yol. Kullanıcıların yemeklerini kaydetmesi için gıda arama ve barkod uç noktalarını kullanın, özel yemek girişleri için tarif analizi uç noktasını kullanın.

Yemek Planlama Platformları

Yemek planlama uygulamaları, belirli makro hedeflere ulaşmak için doğru besin verisine ihtiyaç duyar. API'nin ayrıntılı besin içeriği (70+ besin maddesi), yalnızca kalori ve makroları değil, aynı zamanda mikro besinleri, alerjenleri ve diyet kısıtlaması uyumluluğunu da içeren hassas yemek planı optimizasyonunu mümkün kılar.

Sağlık ve Tele Sağlık

Hastaların beslenmesini izleyen sağlık platformları, mevcut arayüzlerinde doğru gıda kaydı sağlamak için API ile entegre olabilir. Doğrulanmış veri kaynakları (USDA, EFSA, üretici doğrudan) klinik beslenme izleme için gereken doğruluk standartlarını karşılar.

Restoran ve Gıda Hizmeti

Restoran sipariş platformları, menü öğeleri için besin bilgilerini görüntülemek için API'yi kullanabilir. Tarif analizi uç noktası burada özellikle faydalıdır — bir yemeğin malzemelerini gönderin ve her bir öğeyi manuel olarak hesaplamadan tam besin içeriğini alın.

Araştırma ve Akademi

Beslenme araştırmacıları, diyet çalışmaları için gıda kodlamasını standartlaştırmak amacıyla API'yi kullanabilir. Tutarlı, doğrulanmış veriler, katılımcıların bildirdiği beslenme verilerine dayanan çalışmalarda sıkça görülen ölçüm hatalarını azaltır.

Kod Örnekleri

Python: Bir Gıdayı Ara ve Besin Detaylarını Al

import requests

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

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

# Bir gıda ara
search_response = requests.get(
    f"{BASE_URL}/foods/search",
    headers=headers,
    params={"q": "ızgara tavuk göğsü", "per_page": 3}
)

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

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

# İlk sonucun tam detaylarını al
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"Kalori: {nutrition['calories']}")
print(f"Protein: {nutrition['protein']}g")
print(f"Karbonhidrat: {nutrition['carbohydrates']}g")
print(f"Yağ: {nutrition['fat']}g")
print(f"Porsiyon boyutları: {food_detail['serving_sizes']}")

JavaScript: Barkod Tarama Entegrasyonu

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("Ürün veritabanında bulunamadı");
      return null;
    }
    throw new Error(`API hatası: ${response.status}`);
  }

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

// Örnek kullanım
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(`Her ${serving.description} için:`);
  console.log(`  Kalori: ${Math.round(product.nutrition_per_100g.calories * factor)}`);
  console.log(`  Protein: ${(product.nutrition_per_100g.protein * factor).toFixed(1)}g`);
  console.log(`  Karbonhidrat: ${(product.nutrition_per_100g.carbohydrates * factor).toFixed(1)}g`);
  console.log(`  Yağ: ${(product.nutrition_per_100g.fat * factor).toFixed(1)}g`);
}

Swift: Otomatik Tamamlama Arama Alanı Oluşturma

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]
}

Hata Yönetimi En İyi Uygulamaları

API, standart HTTP durum kodlarını kullanır:

Durum Kodu	Anlamı	Yaygın Sebep
200	Başarılı	İstek normal şekilde tamamlandı
400	Geçersiz İstek	Gerekli parametre eksik veya geçersiz değer
401	Yetkisiz	Geçersiz veya eksik API anahtarı
403	Yasak	API anahtarı gerekli kapsamı karşılamıyor
404	Bulunamadı	Gıda ID'si veya barkod veritabanında yok
429	Hız Sınırlandırıldı	Çok fazla istek; hız sınırı başlıklarını kontrol edin
500	Sunucu Hatası	Dahili hata; üssel geri çekilme ile yeniden deneyin

429 yanıtı aldığınızda, Retry-After başlığı, yeniden denemeden önce ne kadar beklemeniz gerektiğini belirtir. Üretim uygulamaları için 429 ve 500 yanıtları için üssel geri çekilme uygulamanız şiddetle önerilir.

Veri Güncelliği ve Güncellemeler

Nutrola'nın veritabanı sürekli olarak güncellenmektedir. Markalı ürün kayıtları, üreticiler değişiklik bildirdiğinde, genellikle 48 saat içinde yenilenir. Devlet veritabanı kayıtları, yeni sürümler yayınlandığında üç ayda bir senkronize edilir.

Uygulamanız API yanıtlarını önbelleğe alıyorsa (bu, performans için önerilir), gıda detay yanıtları için 24 saatlik bir önbellek TTL'si ve arama sonuçları için 1 saatlik bir TTL öneriyoruz. Gıda detay yanıtlarındaki last_verified alanı, kaydın en son ne zaman doğrulandığını gösterir.

Kurumsal müşteriler için, gıda kayıtları güncellendiğinde önbelleğe alınmış verileri proaktif olarak geçersiz kılmak için webhook bildirimleri sunuyoruz; böylece önbellek TTL'sinin sona ermesini beklemek zorunda kalmazsınız.

Başlarken

1. Kaydolun developer.nutrola.com — bir dakikadan kısa sürede tamamlanır
2. Gerekli kapsamlarla bir API anahtarı oluşturun
3. Yukarıdaki curl örneklerini kullanarak ilk isteğinizi yapın
4. Doğrudan tarayıcınızda uç noktaları test edebileceğiniz etkileşimli belgeleri keşfedin developer.nutrola.com/docs
5. Destek, özellik talepleri ve diğer geliştiricilerin neler yaptığını görmek için geliştirici topluluğuna katılın Discord sunucumuzda

Sorularınız varsa, sorunlarla karşılaşırsanız veya bir kurumsal entegrasyonu tartışmak isterseniz, geliştirici ilişkileri ekibimize api@nutrola.com adresinden ulaşabilirsiniz.

SSS

Nutrola API'si ücretsiz mi?

Evet, günde 500 isteği içeren bir ücretsiz katman mevcuttur. Bu, geliştirme, test etme ve küçük ölçekli uygulamalar için uygundur. Daha yüksek trafik için üretim uygulamaları için Büyüme katmanı, günde 25,000 istek ile $49/ay'dan başlar. Yüksek trafik kullanım durumları için özel limitler ile Kurumsal planlar mevcuttur.

API hangi veri formatlarını destekliyor?

API, istekler ve yanıtlar için yalnızca JSON kullanır. Tüm uç noktalar, GET istekleri için standart sorgu parametrelerini ve POST istekleri için JSON istek gövdelerini kabul eder. Yanıt kodlaması UTF-8'dir, bu da tüm desteklenen dillerde gıda isimlerini düzgün bir şekilde işler.

API tarafından sağlanan besin verisi ne kadar doğru?

Nutrola veritabanındaki her kayıt, devlet kaynakları doğrulaması, üretici verileri çapraz kontrolü, AI destekli istatistiksel kontrol ve insan uzman incelemesi dahil olmak üzere çok katmanlı bir doğrulama sürecinden geçmektedir. Doğruluk ölçütümüz, laboratuvar analizine karşı %97.4'tür; bu, kalabalık kaynaklı veritabanları için endüstri ortalaması olan %70-85'e kıyasla oldukça yüksektir. Her gıda kaydı, güven düzeyimizi belirten bir confidence_score alanı içerir.

API'yi ticari bir ürün oluşturmak için kullanabilir miyim?

Evet. API, ticari kullanım için tasarlanmıştır. Ücretsiz katman, hız sınırları içinde ticari ürünler için kullanılabilir. Büyüme ve Kurumsal planlar, uygulama türü üzerinde kısıtlama olmaksızın ticari kullanım hakları içerir. Tam detaylar için developer.nutrola.com adresindeki hizmet şartlarını gözden geçirin.

API, ABD dışındaki gıdaları destekliyor mu?

Evet. Veritabanı, 47 ülkeden markalı ürünleri ve 120'den fazla mutfaktan genel gıdaları kapsamaktadır. Belirli bir pazardan sonuçları önceliklendirmek için arama uç noktalarında country parametresini kullanın. Barkod aramaları, ürünü doğru bölgesel formülasyona otomatik olarak eşleştirir.

Veritabanında olmayan gıdalarla nasıl başa çıkabilirim?

Bir barkod araması 404 dönerse, ürün adını kullanarak metin aramasına geçebilirsiniz. Eğer her iki yaklaşım da gıdayı bulamazsa, geliştirici portalı aracılığıyla eklenmesi için gönderebilirsiniz. API ortakları tarafından gönderilen gıdalar, doğrulama için önceliklendirilir ve genellikle 72 saat içinde eklenir. Kurumsal müşteriler, büyük ürün katalogları için toplu eklemeler talep edebilir.

SDK'lar veya istemci kütüphaneleri mevcut mu?

Python (pip ile: pip install nutrola), JavaScript/TypeScript (npm ile: npm install @nutrola/api) ve Swift (Swift Paket Yöneticisi ile) için resmi istemci kütüphaneleri sunuyoruz. Bu kütüphaneler, kimlik doğrulama, hız sınırlama, yeniden denemeler ve yanıt ayrıştırma işlemlerini yönetir. Go, Ruby ve PHP için topluluk tarafından bakım yapılan kütüphaneler de mevcuttur.