API de Dados Nutricionais da Nutrola: Como Desenvolvedores Podem Acessar Nosso Banco de Dados de Alimentos
Um guia para desenvolvedores sobre a API de Dados Nutricionais da Nutrola. Saiba como acessar nosso banco de dados verificado de alimentos com mais de 3 milhões de registros, explore endpoints, autenticação e casos de uso reais.
Está desenvolvendo um aplicativo de saúde, fitness ou alimentação? Um dos problemas mais difíceis que você vai enfrentar é o de dados nutricionais. Você precisa de informações precisas sobre calorias e macronutrientes para milhares de alimentos, precisa que cubra produtos internacionais e que se mantenha atualizado à medida que os fabricantes reformulam seus produtos.
A maioria dos desenvolvedores começa extraindo dados de bancos de dados governamentais abertos, como o USDA FoodData Central. Isso fornece uma base, mas não cobre produtos de marca de 47 países, refeições de restaurantes ou os milhares de alimentos regionais que os usuários reais consomem diariamente. Preencher essas lacunas por conta própria significa anos de trabalho de curadoria de dados.
A API de Dados Nutricionais da Nutrola oferece aos desenvolvedores acesso ao mesmo banco de dados verificado de alimentos que alimenta nosso aplicativo — mais de 3 milhões de registros, cobrindo ingredientes crus, produtos de marca, refeições de restaurantes e receitas compostas. Cada registro é verificado por meio do nosso processo de controle de qualidade em múltiplas camadas, o mesmo sistema em que confiam mais de 2 milhões de usuários.
Este guia abrange tudo o que você precisa saber para começar a construir com nossa API: arquitetura, autenticação, endpoints, limites de requisições e exemplos de código do mundo real.
Visão Geral da API
A API de Dados Nutricionais da Nutrola é uma API RESTful JSON. Você faz requisições HTTP e recebe respostas JSON. Nenhum SDK é necessário, embora forneçamos bibliotecas cliente para Python, JavaScript e Swift por conveniência.
URL Base
https://api.nutrola.com/v1
Todos os endpoints são servidos via HTTPS. Requisições HTTP simples são rejeitadas.
Principais Funcionalidades
| Funcionalidade | Descrição |
|---|---|
| Busca de Alimentos | Busca por texto completo em mais de 3 milhões de registros de alimentos com filtragem por categoria, marca e país |
| Consulta por Código de Barras | Obtenha dados nutricionais por UPC, EAN ou outros formatos de código de barras |
| Detalhes Nutricionais | Perfil nutricional completo para qualquer alimento (mais de 70 nutrientes incluindo micronutrientes) |
| Tamanhos de Porção | Porções padrão e alternativas com conversões em gramas |
| Análise de Receitas | Envie uma lista de ingredientes e obtenha dados nutricionais combinados |
| Categorias de Alimentos | Navegue pela taxonomia hierárquica de categorias de alimentos |
| Diretório de Marcas | Pesquise e navegue pelos fabricantes de alimentos de marca |
| Autocompletar | Sugestões rápidas de digitação para interfaces de busca de alimentos |
Formato de Resposta
Todas as respostas seguem uma estrutura consistente:
{
"status": "success",
"data": { },
"meta": {
"request_id": "req_abc123",
"rate_limit_remaining": 245,
"rate_limit_reset": "2026-03-10T15:00:00Z"
}
}
As respostas de erro incluem um código de erro legível por máquina e uma mensagem legível por humanos:
{
"status": "error",
"error": {
"code": "FOOD_NOT_FOUND",
"message": "No food entry matches the provided ID.",
"request_id": "req_xyz789"
}
}
Autenticação
Todas as requisições à API exigem uma chave de API passada no cabeçalho Authorization.
Obtendo uma Chave de API
- Crie uma conta de desenvolvedor em developer.nutrola.com
- Navegue até a seção de Chaves de API no seu painel
- Gere uma nova chave e especifique os escopos necessários
- Armazene a chave com segurança — ela será exibida apenas uma vez
Usando Sua Chave de API
Inclua a chave em cada cabeçalho de requisição:
Authorization: Bearer YOUR_API_KEY
Exemplo com curl:
curl -H "Authorization: Bearer ntr_live_abc123def456" \
https://api.nutrola.com/v1/foods/search?q=chicken+breast
Escopos da Chave de API
| Escopo | Nível de Acesso |
|---|---|
foods:read |
Pesquisar e recuperar dados de alimentos (mais comum) |
barcodes:read |
Consulta por código de barras |
recipes:analyze |
Análise nutricional de receitas |
brands:read |
Acesso ao diretório de marcas |
categories:read |
Taxonomia de categorias de alimentos |
As chaves podem ser limitadas a funcionalidades específicas. Uma chave com apenas foods:read não pode acessar consultas por código de barras. Isso segue o princípio do menor privilégio — solicite apenas os escopos que sua aplicação necessita.
Endpoints Principais
Busca de Alimentos
Pesquise no banco de dados por nome, palavra-chave ou frase.
GET /v1/foods/search
Parâmetros:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q |
string | Sim | Consulta de busca (ex.: "grilled chicken breast") |
category |
string | Não | Filtrar por categoria de alimento (ex.: "dairy", "vegetables") |
brand |
string | Não | Filtrar por nome de marca |
country |
string | Não | Código de país ISO 3166-1 alfa-2 (ex.: "US", "DE", "JP") |
verified_only |
boolean | Não | Retornar apenas registros com dados de origem verificados (padrão: true) |
page |
integer | Não | Número da página para paginação (padrão: 1) |
per_page |
integer | Não | Resultados por página, máximo 50 (padrão: 20) |
Exemplo de Requisição:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.nutrola.com/v1/foods/search?q=greek+yogurt&country=US&per_page=5"
Exemplo de Resposta:
{
"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
}
}
Obter Detalhes do Alimento
Recupere o perfil nutricional completo de um alimento específico.
GET /v1/foods/{food_id}
Exemplo de Requisição:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.nutrola.com/v1/foods/food_8f2k9d"
A resposta detalhada inclui a análise completa de nutrientes — mais de 70 nutrientes, incluindo todas as vitaminas, minerais, aminoácidos e perfis de ácidos graxos. Também inclui todos os tamanhos de porção disponíveis e seus equivalentes em gramas.
Resposta Parcial (Nutrientes Principais):
{
"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
}
}
Consulta por Código de Barras
Consulte um produto alimentício pelo seu código de barras.
GET /v1/barcodes/{barcode}
Formatos Suportados: UPC-A, UPC-E, EAN-13, EAN-8
Exemplo de Requisição:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.nutrola.com/v1/barcodes/0049000006346"
A resposta retorna o mesmo objeto de detalhes de alimento que o endpoint /foods/{food_id}, com campos adicionais específicos de código de barras como barcode_format e regional_variants (um array de IDs de alimentos para o mesmo produto em diferentes países, que podem ter formulações diferentes).
Análise de Receitas
Envie uma lista de ingredientes e receba a análise nutricional combinada.
POST /v1/recipes/analyze
Corpo da Requisição:
{
"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" }
]
}
Você também pode enviar ingredientes como texto para análise automática:
{
"name": "Overnight Oats",
"servings": 2,
"ingredients_text": "160g rolled oats, 400ml whole milk, 60g peanut butter, pinch of salt"
}
Resposta:
{
"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 }
]
}
}
Autocompletar
Sugestões rápidas de digitação para construir interfaces de busca.
GET /v1/foods/autocomplete?q={query}
Parâmetros:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q |
string | Sim | Consulta parcial de busca (mínimo 2 caracteres) |
limit |
integer | Não | Máximo de resultados, 1-10 (padrão: 5) |
country |
string | Não | Priorizar resultados deste país |
Os tempos de resposta são otimizados para uso interativo — normalmente abaixo de 50ms. O endpoint de autocompletar retorna objetos simplificados de alimentos (apenas ID, nome, marca e categoria) para renderização rápida.
Limites de Requisições e Preços
Plano Gratuito
O plano gratuito é projetado para desenvolvimento, testes e aplicações de pequena escala:
| Limite | Valor |
|---|---|
| Requisições por dia | 500 |
| Requisições por minuto | 30 |
| Resultados de busca por requisição | 20 |
| Análises de receita por dia | 10 |
| Consultas de código de barras por dia | 100 |
Plano Crescimento
Para aplicações em produção com tráfego moderado:
| Limite | Valor |
|---|---|
| Requisições por dia | 25.000 |
| Requisições por minuto | 300 |
| Resultados de busca por requisição | 50 |
| Análises de receita por dia | 500 |
| Consultas de código de barras por dia | 5.000 |
| Preço | $49/mês |
Plano Empresarial
Para aplicações de alto tráfego, soluções white-label e requisitos personalizados:
| Recurso | Detalhes |
|---|---|
| Requisições por dia | Personalizado (normalmente 100 mil+) |
| Limites de requisição | Personalizados |
| Suporte dedicado | Incluído |
| SLA | Garantia de 99,9% de disponibilidade |
| Exportações de dados personalizadas | Disponível |
| Notificações por webhook | Disponíveis para atualizações de dados |
| Preço | Contate vendas |
As informações de limite de requisições são incluídas em cada resposta da API no objeto meta e nos cabeçalhos de resposta HTTP (X-RateLimit-Remaining, X-RateLimit-Reset).
Casos de Uso Reais
Aplicativos de Fitness e Exercícios
Se você está construindo um aplicativo de fitness e deseja adicionar rastreamento nutricional sem criar um banco de dados de alimentos do zero, a API da Nutrola é o caminho mais rápido. Use os endpoints de busca de alimentos e código de barras para permitir que os usuários registrem refeições, e o endpoint de análise de receitas para registros de refeições personalizadas.
Plataformas de Planejamento de Refeições
Aplicativos de planejamento de refeições precisam de dados nutricionais precisos para gerar planos que atinjam metas específicas de macronutrientes. A análise detalhada de nutrientes da API (mais de 70 nutrientes) permite a otimização precisa do plano alimentar, não apenas calorias e macros, mas micronutrientes, alérgenos e compatibilidade com restrições alimentares.
Saúde e Telemedicina
Plataformas de saúde que monitoram a nutrição dos pacientes podem se integrar com a API para fornecer registro preciso de alimentos em suas interfaces existentes. As fontes de dados verificadas (USDA, EFSA, dados diretos de fabricantes) atendem aos padrões de precisão exigidos para monitoramento nutricional clínico.
Restaurantes e Serviços de Alimentação
Plataformas de pedidos em restaurantes podem usar a API para exibir informações nutricionais dos itens do cardápio. O endpoint de análise de receitas é particularmente útil aqui — envie os ingredientes de um prato e obtenha a análise nutricional completa sem calcular manualmente cada item.
Pesquisa e Meio Acadêmico
Pesquisadores de nutrição podem usar a API para padronizar a codificação de alimentos em estudos dietéticos. Os dados consistentes e verificados reduzem o erro de medição que prejudica estudos que dependem de dados nutricionais relatados pelos participantes.
Exemplos de Código
Python: Buscar um Alimento e Obter Detalhes Nutricionais
import requests
API_KEY = "ntr_live_your_key_here"
BASE_URL = "https://api.nutrola.com/v1"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
# Search for a food
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")
# Get full details for the first result
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"Calories: {nutrition['calories']}")
print(f"Protein: {nutrition['protein']}g")
print(f"Carbs: {nutrition['carbohydrates']}g")
print(f"Fat: {nutrition['fat']}g")
print(f"Serving sizes: {food_detail['serving_sizes']}")
JavaScript: Integração com Leitura de Código de Barras
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("Product not found in database");
return null;
}
throw new Error(`API error: ${response.status}`);
}
const data = await response.json();
return data.data;
}
// Example usage
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(`Per ${serving.description}:`);
console.log(` Calories: ${Math.round(product.nutrition_per_100g.calories * factor)}`);
console.log(` Protein: ${(product.nutrition_per_100g.protein * factor).toFixed(1)}g`);
console.log(` Carbs: ${(product.nutrition_per_100g.carbohydrates * factor).toFixed(1)}g`);
console.log(` Fat: ${(product.nutrition_per_100g.fat * factor).toFixed(1)}g`);
}
Swift: Construindo um Campo de Busca com Autocompletar
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]
}
Melhores Práticas de Tratamento de Erros
A API usa códigos de status HTTP padrão:
| Código de Status | Significado | Causa Comum |
|---|---|---|
| 200 | Sucesso | Requisição concluída normalmente |
| 400 | Requisição Inválida | Parâmetro obrigatório ausente ou valor inválido |
| 401 | Não Autorizado | Chave de API inválida ou ausente |
| 403 | Proibido | A chave de API não possui o escopo necessário |
| 404 | Não Encontrado | ID de alimento ou código de barras não está no banco de dados |
| 429 | Limite de Requisições Excedido | Muitas requisições; verifique os cabeçalhos de limite |
| 500 | Erro do Servidor | Erro interno; tente novamente com backoff exponencial |
Quando você recebe uma resposta 429, o cabeçalho Retry-After informa quantos segundos esperar antes de tentar novamente. Implementar backoff exponencial para respostas 429 e 500 é altamente recomendado para aplicações em produção.
Atualização e Frescor dos Dados
O banco de dados da Nutrola é atualizado continuamente. Os registros de produtos de marca são atualizados quando os fabricantes reportam alterações, normalmente dentro de 48 horas. Os registros de bancos de dados governamentais são sincronizados trimestralmente quando novas versões são publicadas.
Se sua aplicação faz cache das respostas da API (o que recomendamos para melhor desempenho), sugerimos um TTL de cache de 24 horas para respostas de detalhes de alimentos e 1 hora para resultados de busca. O campo last_verified nas respostas de detalhes de alimentos informa quando o registro foi confirmado como preciso pela última vez.
Para clientes empresariais, oferecemos notificações por webhook quando registros de alimentos são atualizados, para que sua aplicação possa invalidar dados em cache de forma proativa, em vez de esperar o TTL do cache expirar.
Como Começar
- Cadastre-se em developer.nutrola.com — leva menos de um minuto
- Gere uma chave de API com os escopos necessários
- Faça sua primeira requisição usando os exemplos de curl acima
- Explore a documentação interativa em developer.nutrola.com/docs onde você pode testar endpoints diretamente no seu navegador
- Junte-se à comunidade de desenvolvedores no nosso servidor Discord para suporte, solicitações de recursos e para ver o que outros desenvolvedores estão construindo
Se você tiver dúvidas, encontrar problemas ou quiser discutir uma integração empresarial, entre em contato com nossa equipe de relações com desenvolvedores em api@nutrola.com.
Perguntas Frequentes
A API da Nutrola é gratuita?
Sim, existe um plano gratuito que inclui 500 requisições por dia. Isso é adequado para desenvolvimento, testes e aplicações de pequena escala. Para aplicações em produção com maior tráfego, o plano Crescimento começa em $49 por mês com 25.000 requisições diárias. Planos Empresariais com limites personalizados estão disponíveis para casos de uso de alto tráfego.
Quais formatos de dados a API suporta?
A API usa exclusivamente JSON para requisições e respostas. Todos os endpoints aceitam parâmetros de consulta padrão para requisições GET e corpos de requisição JSON para requisições POST. A codificação de resposta é UTF-8, que lida adequadamente com nomes de alimentos em todos os idiomas suportados.
Quão precisos são os dados nutricionais fornecidos pela API?
Cada registro no banco de dados da Nutrola passa por um processo de verificação em múltiplas camadas, incluindo validação de fontes governamentais, referência cruzada com dados de fabricantes, verificação estatística por IA e revisão por especialistas humanos. Nosso benchmark de precisão é de 97,4% em comparação com análises laboratoriais, contra uma média da indústria de 70-85% para bancos de dados colaborativos. Cada registro de alimento inclui um campo confidence_score indicando nosso nível de certeza.
Posso usar a API para construir um produto comercial?
Sim. A API é projetada para uso comercial. O plano gratuito pode ser usado para produtos comerciais dentro de seus limites de requisição. Os planos Crescimento e Empresarial incluem direitos de uso comercial sem restrições sobre o tipo de aplicação. Consulte os termos de serviço em developer.nutrola.com para detalhes completos.
A API suporta alimentos de fora dos Estados Unidos?
Sim. O banco de dados cobre produtos de marca de 47 países e alimentos genéricos de mais de 120 culinárias. Use o parâmetro country nos endpoints de busca para priorizar resultados de um mercado específico. As consultas por código de barras identificam automaticamente o produto com a formulação regional correta.
Como lidar com alimentos que não estão no banco de dados?
Se uma consulta por código de barras retornar um 404, você pode recorrer a uma busca por texto usando o nome do produto. Se nenhuma abordagem encontrar o alimento, você pode enviá-lo para adição através do portal de desenvolvedores. Alimentos enviados por parceiros da API são priorizados para verificação e normalmente adicionados em até 72 horas. Clientes empresariais podem solicitar adições em lote para grandes catálogos de produtos.
Existem SDKs ou bibliotecas cliente disponíveis?
Fornecemos bibliotecas cliente oficiais para Python (via pip: pip install nutrola), JavaScript/TypeScript (via npm: npm install @nutrola/api) e Swift (via Swift Package Manager). Essas bibliotecas lidam com autenticação, limites de requisição, tentativas e análise de respostas. Bibliotecas mantidas pela comunidade estão disponíveis para Go, Ruby e PHP.
Pronto para Transformar seu Rastreamento Nutricional?
Junte-se a milhares que transformaram sua jornada de saúde com o Nutrola!
