Nutrola의 영양 데이터 API: 개발자가 식품 데이터베이스에 접근하는 방법
Nutrola의 영양 데이터 API에 대한 개발자 가이드입니다. 300만 개 이상의 검증된 식품 데이터베이스에 접근하고, 엔드포인트, 인증 방법, 실제 사용 사례를 탐색해 보세요.
건강, 피트니스 또는 식품 관련 앱을 개발하고 계신가요? 가장 어려운 문제 중 하나는 영양 데이터입니다. 수천 가지 식품에 대한 정확한 칼로리와 매크로 정보를 필요로 하며, 국제 제품을 포함해야 하고, 제조업체가 제품을 재구성할 때마다 최신 정보를 유지해야 합니다.
대부분의 개발자는 USDA FoodData Central과 같은 공개 정부 데이터베이스에서 데이터를 가져오는 것으로 시작합니다. 이는 기본적인 토대를 제공하지만, 47개국의 브랜드 제품, 레스토랑 식사, 그리고 실제 사용자들이 매일 소비하는 수천 가지 지역 식품을 포함하지 않습니다. 이러한 공백을 직접 채우려면 수년간의 데이터 큐레이션 작업이 필요합니다.
Nutrola의 영양 데이터 API는 개발자에게 우리 앱을 지원하는 동일한 검증된 식품 데이터베이스에 접근할 수 있는 기회를 제공합니다. 300만 개 이상의 항목이 포함되어 있으며, 원재료, 브랜드 제품, 레스토랑 식사, 복합 레시피를 아우릅니다. 모든 항목은 200만 명 이상의 사용자가 신뢰하는 다층 품질 관리 프로세스를 통해 검증됩니다.
이 가이드는 API를 사용하여 개발을 시작하는 데 필요한 모든 정보를 제공합니다: 아키텍처, 인증, 엔드포인트, 속도 제한, 실제 코드 예제 등을 포함합니다.
API 개요
Nutrola 영양 데이터 API는 RESTful JSON API입니다. HTTP 요청을 보내면 JSON 응답을 받습니다. SDK는 필요하지 않지만, 편의를 위해 Python, JavaScript, Swift용 클라이언트 라이브러리를 제공합니다.
기본 URL
https://api.nutrola.com/v1
모든 엔드포인트는 HTTPS를 통해 제공됩니다. 일반 HTTP 요청은 거부됩니다.
주요 기능
| 기능 | 설명 |
|---|---|
| 식품 검색 | 300만 개 이상의 식품 항목에 대한 전체 텍스트 검색, 카테고리, 브랜드, 국가별 필터링 |
| 바코드 조회 | UPC, EAN 또는 기타 바코드 형식으로 영양 데이터 조회 |
| 영양 세부정보 | 모든 식품에 대한 완전한 영양 프로필 (70개 이상의 영양소 포함) |
| 서빙 사이즈 | 표준 및 대체 서빙 사이즈와 그램 변환 |
| 레시피 분석 | 재료 목록을 제출하고 결합된 영양 데이터를 받기 |
| 식품 카테고리 | 계층적 식품 카테고리 분류 탐색 |
| 브랜드 디렉토리 | 브랜드 식품 제조업체 검색 및 탐색 |
| 자동 완성 | 식품 검색 인터페이스를 위한 빠른 자동 완성 제안 |
응답 형식
모든 응답은 일관된 구조를 따릅니다:
{
"status": "success",
"data": { },
"meta": {
"request_id": "req_abc123",
"rate_limit_remaining": 245,
"rate_limit_reset": "2026-03-10T15:00:00Z"
}
}
오류 응답에는 기계 판독 가능한 오류 코드와 인간이 읽을 수 있는 메시지가 포함됩니다:
{
"status": "error",
"error": {
"code": "FOOD_NOT_FOUND",
"message": "제공된 ID와 일치하는 식품 항목이 없습니다.",
"request_id": "req_xyz789"
}
}
인증
모든 API 요청은 Authorization 헤더에 API 키를 포함해야 합니다.
API 키 받기
- developer.nutrola.com에서 개발자 계정을 생성하세요.
- 대시보드에서 API 키 섹션으로 이동하세요.
- 새 키를 생성하고 필요한 범위를 지정하세요.
- 키를 안전하게 보관하세요 — 한 번만 표시됩니다.
API 키 사용하기
모든 요청 헤더에 키를 포함하세요:
Authorization: Bearer YOUR_API_KEY
curl 예제:
curl -H "Authorization: Bearer ntr_live_abc123def456" \
https://api.nutrola.com/v1/foods/search?q=chicken+breast
API 키 범위
| 범위 | 접근 수준 |
|---|---|
foods:read |
식품 데이터 검색 및 조회 (가장 일반적) |
barcodes:read |
바코드 조회 |
recipes:analyze |
레시피 영양 분석 |
brands:read |
브랜드 디렉토리 접근 |
categories:read |
식품 카테고리 분류 |
키는 특정 기능에 맞게 범위가 설정될 수 있습니다. foods:read만 있는 키는 바코드 조회에 접근할 수 없습니다. 이는 최소 권한 원칙을 따르며, 애플리케이션에 필요한 범위만 요청하세요.
핵심 엔드포인트
식품 검색
이름, 키워드 또는 구문으로 데이터베이스를 검색합니다.
GET /v1/foods/search
매개변수:
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
q |
string | 예 | 검색 쿼리 (예: "grilled chicken breast") |
category |
string | 아니오 | 식품 카테고리별 필터 (예: "dairy", "vegetables") |
brand |
string | 아니오 | 브랜드 이름별 필터 |
country |
string | 아니오 | ISO 3166-1 alpha-2 국가 코드 (예: "US", "DE", "JP") |
verified_only |
boolean | 아니오 | 검증된 출처 데이터만 반환 (기본값: true) |
page |
integer | 아니오 | 페이지 번호 (기본값: 1) |
per_page |
integer | 아니오 | 페이지당 결과 수, 최대 50 (기본값: 20) |
예제 요청:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.nutrola.com/v1/foods/search?q=greek+yogurt&country=US&per_page=5"
예제 응답:
{
"status": "success",
"data": {
"results": [
{
"id": "food_8f2k9d",
"name": "Greek Yogurt, Plain, Nonfat",
"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 container (170g)",
"grams": 170
}
}
],
"total_results": 342,
"page": 1,
"per_page": 5
}
}
식품 세부정보 가져오기
특정 식품에 대한 완전한 영양 프로필을 조회합니다.
GET /v1/foods/{food_id}
예제 요청:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.nutrola.com/v1/foods/food_8f2k9d"
상세 응답에는 70개 이상의 영양소를 포함한 전체 영양 분해가 포함됩니다. 또한 모든 사용 가능한 서빙 사이즈와 그램 환산도 포함됩니다.
부분 응답 (주요 영양소):
{
"status": "success",
"data": {
"id": "food_8f2k9d",
"name": "Greek Yogurt, Plain, Nonfat",
"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 container (170g)", "grams": 170 },
{ "description": "1 cup (245g)", "grams": 245 },
{ "description": "1 tbsp (15g)", "grams": 15 },
{ "description": "100g", "grams": 100 }
],
"allergens": ["milk"],
"source": "USDA",
"source_id": "170903",
"last_verified": "2026-02-15",
"confidence_score": 0.98
}
}
바코드 조회
바코드로 식품 제품을 조회합니다.
GET /v1/barcodes/{barcode}
지원되는 형식: UPC-A, UPC-E, EAN-13, EAN-8
예제 요청:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.nutrola.com/v1/barcodes/0049000006346"
응답은 /foods/{food_id} 엔드포인트와 동일한 식품 세부정보 객체를 반환하며, barcode_format 및 regional_variants와 같은 바코드 전용 필드가 추가됩니다 (다른 국가에서 동일한 제품의 식품 ID 배열, 서로 다른 포뮬레이션을 가질 수 있음).
레시피 분석
재료 목록을 제출하고 결합된 영양 분해를 받습니다.
POST /v1/recipes/analyze
요청 본문:
{
"name": "Overnight Oats",
"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": "pinch of salt" }
]
}
재료를 텍스트로 제출하여 자동으로 구문 분석할 수도 있습니다:
{
"name": "Overnight Oats",
"servings": 2,
"ingredients_text": "160g rolled oats, 400ml whole milk, 60g peanut butter, pinch of salt"
}
응답:
{
"status": "success",
"data": {
"name": "Overnight Oats",
"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 rolled oats", "matched_food": "food_3k8m2n", "confidence": 0.97 },
{ "input": "400ml whole milk", "matched_food": "food_9p4q7r", "confidence": 0.99 },
{ "input": "60g peanut butter", "matched_food": "food_1a5b8c", "confidence": 0.96 },
{ "input": "pinch of salt", "matched_food": "food_6d2e9f", "confidence": 0.88 }
]
}
}
자동 완성
검색 인터페이스 구축을 위한 빠른 자동 완성 제안.
GET /v1/foods/autocomplete?q={query}
매개변수:
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
q |
string | 예 | 부분 검색 쿼리 (최소 2자) |
limit |
integer | 아니오 | 최대 결과 수, 1-10 (기본값: 5) |
country |
string | 아니오 | 이 국가에서 결과 우선 순위 지정 |
응답 시간은 대화형 사용을 위해 최적화되어 있으며, 일반적으로 50ms 이내입니다. 자동 완성 엔드포인트는 빠른 렌더링을 위해 단순화된 식품 객체(ID, 이름, 브랜드, 카테고리만 포함)를 반환합니다.
속도 제한 및 가격
무료 티어
무료 티어는 개발, 테스트 및 소규모 애플리케이션을 위해 설계되었습니다:
| 제한 | 값 |
|---|---|
| 하루 요청 수 | 500 |
| 분당 요청 수 | 30 |
| 요청당 식품 검색 결과 수 | 20 |
| 하루 레시피 분석 수 | 10 |
| 하루 바코드 조회 수 | 100 |
성장 티어
중간 트래픽을 가진 프로덕션 애플리케이션을 위한:
| 제한 | 값 |
|---|---|
| 하루 요청 수 | 25,000 |
| 분당 요청 수 | 300 |
| 요청당 식품 검색 결과 수 | 50 |
| 하루 레시피 분석 수 | 500 |
| 하루 바코드 조회 수 | 5,000 |
| 가격 | $49/월 |
엔터프라이즈 티어
고트래픽 애플리케이션, 화이트 라벨 솔루션, 맞춤형 요구 사항을 위한:
| 기능 | 세부사항 |
|---|---|
| 하루 요청 수 | 맞춤형 (일반적으로 100K+) |
| 속도 제한 | 맞춤형 |
| 전담 지원 | 포함 |
| SLA | 99.9% 가동 시간 보장 |
| 맞춤형 데이터 내보내기 | 가능 |
| 데이터 업데이트를 위한 웹훅 알림 | 가능 |
| 가격 | 영업팀에 문의 |
속도 제한 정보는 모든 API 응답의 meta 객체와 HTTP 응답 헤더(X-RateLimit-Remaining, X-RateLimit-Reset)에 포함됩니다.
실제 사용 사례
피트니스 및 운동 앱
피트니스 앱을 개발하고 영양 추적 기능을 추가하고 싶다면 Nutrola의 API가 가장 빠른 경로입니다. 식품 검색 및 바코드 엔드포인트를 사용하여 사용자가 식사를 기록할 수 있도록 하고, 레시피 분석 엔드포인트를 통해 맞춤형 식사 항목을 추가할 수 있습니다.
식사 계획 플랫폼
식사 계획 앱은 특정 매크로 목표를 달성하기 위해 정확한 영양 데이터가 필요합니다. API의 상세한 영양 분해(70개 이상의 영양소)는 칼로리와 매크로뿐만 아니라 미량 영양소, 알레르기 유발 물질 및 식이 제한 호환성을 고려한 정밀한 식사 계획 최적화를 가능하게 합니다.
의료 및 원격 의료
환자의 영양을 모니터링하는 의료 플랫폼은 API와 통합하여 기존 인터페이스 내에서 정확한 식품 기록을 제공할 수 있습니다. 검증된 데이터 출처(USDA, EFSA, 제조업체 직접)는 임상 영양 모니터링에 필요한 정확성 기준을 충족합니다.
레스토랑 및 식품 서비스
레스토랑 주문 플랫폼은 API를 사용하여 메뉴 항목에 대한 영양 정보를 표시할 수 있습니다. 레시피 분석 엔드포인트는 특히 유용합니다 — 요리의 재료를 제출하고 각 항목을 수동으로 계산하지 않고도 전체 영양 분해를 받을 수 있습니다.
연구 및 학계
영양 연구원들은 API를 사용하여 식이 연구에서 식품 코딩을 표준화할 수 있습니다. 일관되고 검증된 데이터는 참가자가 보고한 영양 데이터에 의존하는 연구에서 발생하는 측정 오류를 줄입니다.
코드 예제
Python: 식품 검색 및 영양 세부정보 가져오기
import requests
API_KEY = "ntr_live_your_key_here"
BASE_URL = "https://api.nutrola.com/v1"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
# 식품 검색
search_response = requests.get(
f"{BASE_URL}/foods/search",
headers=headers,
params={"q": "chicken breast grilled", "per_page": 3}
)
results = search_response.json()["data"]["results"]
for food in results:
print(f"{food['name']} - {food['nutrition_per_100g']['calories']} cal/100g")
# 첫 번째 결과에 대한 전체 세부정보 가져오기
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"칼로리: {nutrition['calories']}")
print(f"단백질: {nutrition['protein']}g")
print(f"탄수화물: {nutrition['carbohydrates']}g")
print(f"지방: {nutrition['fat']}g")
print(f"서빙 사이즈: {food_detail['serving_sizes']}")
JavaScript: 바코드 스캔 통합
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("데이터베이스에서 제품을 찾을 수 없습니다.");
return null;
}
throw new Error(`API 오류: ${response.status}`);
}
const data = await response.json();
return data.data;
}
// 사용 예
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(`1회 제공량당:`);
console.log(` 칼로리: ${Math.round(product.nutrition_per_100g.calories * factor)}`);
console.log(` 단백질: ${(product.nutrition_per_100g.protein * factor).toFixed(1)}g`);
console.log(` 탄수화물: ${(product.nutrition_per_100g.carbohydrates * factor).toFixed(1)}g`);
console.log(` 지방: ${(product.nutrition_per_100g.fat * factor).toFixed(1)}g`);
}
Swift: 자동 완성 검색 필드 구축
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]
}
오류 처리 모범 사례
API는 표준 HTTP 상태 코드를 사용합니다:
| 상태 코드 | 의미 | 일반적인 원인 |
|---|---|---|
| 200 | 성공 | 요청이 정상적으로 완료됨 |
| 400 | 잘못된 요청 | 필수 매개변수 누락 또는 잘못된 값 |
| 401 | 인증되지 않음 | 잘못되거나 누락된 API 키 |
| 403 | 금지됨 | API 키에 필요한 범위가 없음 |
| 404 | 찾을 수 없음 | 식품 ID 또는 바코드가 데이터베이스에 없음 |
| 429 | 속도 제한 | 너무 많은 요청; 속도 제한 헤더 확인 |
| 500 | 서버 오류 | 내부 오류; 지수 백오프를 사용하여 재시도 |
429 응답을 받으면 Retry-After 헤더가 재시도하기 전에 기다려야 할 시간을 알려줍니다. 프로덕션 애플리케이션에서는 429 및 500 응답에 대해 지수 백오프를 구현하는 것이 강력히 권장됩니다.
데이터 신선도 및 업데이트
Nutrola의 데이터베이스는 지속적으로 업데이트됩니다. 브랜드 제품 항목은 제조업체가 변경 사항을 보고할 때마다 갱신되며, 일반적으로 48시간 이내에 이루어집니다. 정부 데이터베이스 항목은 새로운 릴리스가 발표될 때마다 분기별로 동기화됩니다.
API 응답을 캐시하는 경우(성능을 위해 권장됨), 식품 세부정보 응답에 대한 캐시 TTL은 24시간, 검색 결과에 대한 캐시 TTL은 1시간으로 설정하는 것이 좋습니다. 식품 세부정보 응답의 last_verified 필드는 항목이 마지막으로 확인된 정확한 시점을 알려줍니다.
엔터프라이즈 고객을 위해 식품 항목이 업데이트될 때 웹훅 알림을 제공하여 애플리케이션이 캐시된 데이터를 사전적으로 무효화할 수 있도록 지원합니다.
시작하기
- 가입하기 developer.nutrola.com — 1분도 걸리지 않습니다.
- API 키 생성하기 필요한 범위를 설정하세요.
- 첫 번째 요청하기 위의 curl 예제를 사용하세요.
- 인터랙티브 문서 탐색하기 developer.nutrola.com/docs에서 브라우저에서 직접 엔드포인트를 테스트할 수 있습니다.
- 개발자 커뮤니티에 참여하기 Discord 서버에서 지원, 기능 요청 및 다른 개발자들이 무엇을 만들고 있는지 확인하세요.
질문이 있거나 문제가 발생하거나 엔터프라이즈 통합에 대해 논의하고 싶다면 api@nutrola.com으로 개발자 관계 팀에 문의하세요.
FAQ
Nutrola API는 무료로 사용할 수 있나요?
네, 하루 500개의 요청을 포함하는 무료 티어가 있습니다. 이는 개발, 테스트 및 소규모 애플리케이션에 적합합니다. 더 높은 트래픽을 가진 프로덕션 애플리케이션을 위해 성장 티어는 월 $49에 25,000개의 일일 요청을 제공합니다. 엔터프라이즈 플랜은 고트래픽 사용 사례를 위한 맞춤형 한도를 제공합니다.
API가 지원하는 데이터 형식은 무엇인가요?
API는 요청 및 응답 모두에 대해 JSON만 사용합니다. 모든 엔드포인트는 GET 요청에 대한 표준 쿼리 매개변수와 POST 요청에 대한 JSON 요청 본문을 수용합니다. 응답 인코딩은 UTF-8로, 모든 지원 언어의 식품 이름을 적절하게 처리합니다.
API에서 제공하는 영양 데이터의 정확도는 얼마나 되나요?
Nutrola 데이터베이스의 모든 항목은 정부 출처 검증, 제조업체 데이터 교차 검증, AI 기반 통계 검사, 인간 전문가 검토를 포함한 다층 검증 프로세스를 거칩니다. 우리의 정확성 기준은 실험실 분석에 대해 97.4%이며, 크라우드소싱 데이터베이스의 산업 평균인 70-85%에 비해 높은 수치입니다. 각 식품 항목에는 우리의 확신 수준을 나타내는 confidence_score 필드가 포함되어 있습니다.
API를 사용하여 상업 제품을 구축할 수 있나요?
네. API는 상업적 사용을 위해 설계되었습니다. 무료 티어는 해당 속도 제한 내에서 상업 제품에 사용할 수 있습니다. 성장 및 엔터프라이즈 플랜은 애플리케이션 유형에 대한 제한 없이 상업적 사용 권한을 포함합니다. 전체 세부정보는 developer.nutrola.com의 서비스 약관을 검토하세요.
API는 미국 외의 식품을 지원하나요?
네. 데이터베이스는 47개국의 브랜드 제품과 120개 이상의 요리에서 일반 식품을 포함합니다. 검색 엔드포인트에서 country 매개변수를 사용하여 특정 시장의 결과를 우선적으로 표시할 수 있습니다. 바코드 조회는 자동으로 제품을 올바른 지역 포뮬레이션에 맞춥니다.
데이터베이스에 없는 식품을 어떻게 처리하나요?
바코드 조회가 404를 반환하면 제품 이름을 사용하여 텍스트 검색으로 대체할 수 있습니다. 두 가지 방법 모두 식품을 찾지 못할 경우, 개발자 포털을 통해 추가 요청을 제출할 수 있습니다. API 파트너가 제출한 식품은 검증 우선 순위가 부여되며 일반적으로 72시간 이내에 추가됩니다. 엔터프라이즈 고객은 대규모 제품 카탈로그에 대한 일괄 추가 요청을 할 수 있습니다.
SDK 또는 클라이언트 라이브러리를 사용할 수 있나요?
우리는 Python(pip install nutrola), JavaScript/TypeScript(npm install @nutrola/api), Swift(스위프트 패키지 관리자)를 위한 공식 클라이언트 라이브러리를 제공합니다. 이 라이브러리는 인증, 속도 제한, 재시도 및 응답 구문 분석을 처리합니다. Go, Ruby 및 PHP용 커뮤니티 유지 관리 라이브러리도 사용할 수 있습니다.
