Документация по API НФЛ

Создавайте соответствующие требованиям этикетки с информацией о пищевой ценности, управляйте рецептами и программно извлекайте данные о пищевой ценности. Сегодня для каждого соответствующего требованиям аккаунта работают две вещи: встраивание живой метки и экспорт, отрисованный на сервереREST API для доступа к ресурсам находится на стадии раннего доступа в рамках бизнес-плана.

API принимает и возвращает только JSON (конечные точки для рендеринга меток возвращают бинарный файл).

Определение

https://nutritionfactlabel.com/api/v1

конечная точка API

Все REST-ресурсы находятся под одним версионированным базовым URL-адресом. Критические изменения всегда поставляются только под новым префиксом версии. Во время раннего доступа в приветственном письме будет подтвержден активный базовый URL-адрес для ваших ключей.

Сводная таблица шаблонов URL-адресов ресурсов

/v1/recipes
/v1/recipes/{RECIPE_ID}
/v1/recipes/{RECIPE_ID}/label.{svg|png|pdf}
/v1/ingredients
/v1/ingredients/{INGREDIENT_ID}
/v1/analyze

Аутентификация

Подтверждайте каждый запрос с помощью вашего секретного ключа в Authorization заголовок. Ключи привязаны к вашей учетной записи и предоставляют доступ к функциям вашего тарифного плана: те же серверные механизмы, что и в приложении.

Храните ключи в секрете. Никогда не внедряйте их в клиентский код; используйте прокси через бэкэнд. Немедленно сообщайте о скомпрометированном ключе через службу поддержки.

Пример запроса

curl https://nutritionfactlabel.com/api/v1/recipes \
  -H 'Authorization: Bearer nfl_live_9f30c2...'

Ограничения скорости

Для обеспечения справедливости и стабильности: 60 запросов в минуту за клавишу; количество отрисовок меток дополнительно ограничено. 5 одновременных; объем тела запроса составляет 1 МБ. При превышении лимита вы получите ошибку. 429 с Retry-After заголовок.

Пример ответа

HTTP/2 429 Too Many Requests
Retry-After: 22

{ "error": { "code": "rate_limited",
  "message": "Try again in 22 seconds." } }

Встраивание живой метки Доступно сейчас

Отображение постоянно актуальной метки на любом веб-сайте без ключа API. Включение встраивания в рецепт в генераторе (строка рецепта → Встроить) чтобы получить его публичный токен.

Высота тега скрипта изменяется автоматически; обновите рецепт в NFL, и все страницы, отображающие встроенный контент, обновятся. Для тарифных планов Professional и Business отключение встроенного контента немедленно аннулирует токен.

Определение: тег скрипта

<script src="https://nutritionfactlabel.com/embed.js"
        data-label="YOUR_EMBED_TOKEN"
        data-width="290"></script>

Альтернативный вариант: iframe

<iframe
  src="https://nutritionfactlabel.com/embed/TOKEN"
  width="290" height="560" frameborder="0"
  title="Nutrition Facts"></iframe>

Экспорт этикеток Доступно сейчас

Файлы SVG/PNG/PDF обрабатываются на стороне сервера тем же движком, что и приложение, с соблюдением правил обработки (форматы, типы файлов, водяные знаки) на этапе развертывания. Вызывайте напрямую с помощью токена сессии, пока ключи API не станут общедоступными. Возвращает двоичный файл или 403 вне вашего плана.

Два замечания по поводу совместимости с экспортом внутри приложения. Приложение отображается в браузере, поэтому используйте этот адрес, если вам нужно получить метку без неё. jpg в настоящее время возвращает байты PNG, в то время как eps и ai Это форматы, доступные только для экспорта, которые конечная точка не поддерживает.

Определение

POST /functions/v1/export-label
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "fileType": "pdf",
  "data": { ...label state },
  "extra": { }
}

Рецепты Ранний доступ · Бизнес

Основной объект: ингредиенты, порции и label_format (152 формата в 114 странах) выдают вычисленные значения label: питательные вещества (округленные по юрисдикциям), список ингредиентов, аллергены.

Ключевые характеристики: id, name, servings, serving_weight_g, label_format, label (вычислено), embed_enabledвременные метки.

Определение

GET    /v1/recipes
POST   /v1/recipes
GET    /v1/recipes/{ID}
PUT    /v1/recipes/{ID}
DELETE /v1/recipes/{ID}
GET    /v1/recipes/{ID}/label.pdf

Пример ответа

{
  "id": "rcp_2m4k9q",
  "name": "Chocolate Chip Cookies",
  "servings": 12,
  "serving_weight_g": 28,
  "label_format": "standard",
  "label": {
    "calories": 140,
    "total_fat_g": 7,
    "allergens": ["wheat","milk","soy"],
    ...
  },
  "embed_enabled": false
}

Ингредиенты Ранний доступ · Бизнес

Пользовательские ингредиенты с указанием пищевой ценности на 100 г, видов аллергенов и возможностью расчета стоимости, идентичные тем, что создаются в приложении, доступны для поиска в генераторе. Ингредиенты соответствуют требованиям Министерства сельского хозяйства США. usda:{fdc_id}; набор "archived": true в архив (по умолчанию исключено из списков).

Определение

GET    /v1/ingredients
POST   /v1/ingredients
GET    /v1/ingredients/{ID}
PUT    /v1/ingredients/{ID}
DELETE /v1/ingredients/{ID}

Пример запроса

POST /v1/ingredients

{
  "name": "Organic almond flour",
  "nutrients_per_100g": {
    "calories": 571, "total_fat_g": 50,
    "protein_g": 21, "dietary_fiber_g": 10
  },
  "allergens": ["tree_nuts"],
  "cost_per_unit": 12.5, "unit": "kg"
}

Анализ пищевой ценности Ранний доступ · Бизнес

Одноразовый анализ без сохранения рецепта. Возвращает тот же результат. label объект плюс claims: заявления о содержании питательных веществ, которым соответствуют указанные значения (например) «хороший источник клетчатки») с указанием ссылок на их данные в CFR. Несовпадающие имена сопоставляются с данными USDA.

Пример запроса

POST /v1/analyze

{
  "label_format": "standard",
  "servings": 12,
  "serving_weight_g": 28,
  "ingredients": [
    { "ingredient_id": "usda:173410", "grams": 120 },
    { "name": "brown sugar", "grams": 80 }
  ]
}

Ошибки

Обычные HTTP-коды; тела ошибок представляют собой JSON со стабильным машинным кодом и сообщением для человека. 400 некорректный ввод · 401 Неверный ключ · 403 вне вашего плана · 404 не найдено / не ваше · 429 Ограничение скорости · 500 Повторить попытку с задержкой.

Пример ответа

{
  "error": {
    "code": "plan_format_not_allowed",
    "message": "The 'eu-1169' label format
      requires the Professional plan."
  }
}

Получение доступа

Для встраивания не требуется ключ; его можно включить для каждого рецепта отдельно (Professional+). Ранний доступ к REST API включен в стоимость. Бизнес план: электронная почта support@nutritionfactlabel.com Ключи будут отправлены на ваш электронный адрес, указанный в учетной записи, и предоставлены в течение одного рабочего дня.

Не хватает нужной вам конечной точки? Сообщите нам. Партнеры, предоставляющие ранний доступ, определяют дальнейшую стратегию развития.

Переход на бизнес-версию