Аналіз харчування та документація з обробки природних мов

Цей API охоплює всі ключові випадки використання, пов’язані з обробкою природних мов рецептів та тексту їжі та аналізом поживності. В API використовується NLP (обробка натуральної мови), яка дозволяє витягувати харчові суб’єкти з неструктурованого тексту.

Покриті випадки використання

Повний аналіз рецептів їжі в режимі реального часу - витяг об'єкта, вимір міри та кількості з розрахунком відповідного харчування для рецепта та відповідних ярликів здоров'я та дієти. Нарешті, він регулює кількість певних інгредієнтів, враховуючи процес приготування. Наприклад, він розраховує поглинання олії для смажених рецептів, виключає тверді речовини із запасів та рецептів бульйону, обчислює поглинання маринату для маринатів та багато іншого.
Вилучення харчових суб’єктів із розмірами та кількістю з неструктурованого тексту
Використання в чат-ботах, що транскрибують природну мову до тексту.

Повний аналіз рецептів

Шлях: https://api.edamam.com/api/nutrition-details

Повертає харчову інформацію на основі запиту POST щодо вмісту рецепта

Наступні параметри є частиною URL-адреси запиту POST:

Параметр Обов’язковий тип Опис

app_id	так	Рядок	Ваш 3-масштабний ідентифікатор програми
app_key	так	Рядок	Ваш ключ програми 3scale
сили	ні	Змушує переоцінити рецепт. Значення, якщо воно є, ігнорується.

Запит на аналіз рецептів

Ви будете використовувати запит POST для надсилання вмісту рецепта, точніше заголовка рецепту та списку інгредієнтів.

Відповідь, яку API поверне, міститиме харчовий аналіз рецепта на основі наданої інформації.

Вміст запиту повинен бути об'єктом JSON у наступному форматі:

Назва Обов’язковий опис

заголовок	так	загальна назва рецепта
інгр	так	інгредієнти (масив рядків)
URL-адреса	ні	URL місця розташування рецепта
резюме	ні	короткий опис рецепта
урожайність	ні	кількість порцій *
ttime	ні	загальний час на підготовку
img	ні	посилання на зображення (абсолютне)
преп	ні	інструкції з підготовки (вільний текст)
кухня	ні	тип кухні
тип їжі	ні	тип їжі
тип посуду	ні	тип страви

* Хоча yeld не є необхідним вкладом, якщо він присутній, він повинен мати сенс з точки зору споживача. Занадто висока або занадто низька вага на порцію вплине на харчування на порцію, і рецепт не пройде нашу автоматизовану перевірку якості. Якщо це трапиться, API поверне помилку 555.
Якщо не вказано врожайність, Едамам обчислить очікуваний вихід рецептури.

Запит повинен містити заголовок

Нові рецепти, повторне подання та кількість ліцензій

Після того, як ви подаєте рецепт через API, ви починаєте платити Edamam щомісячну плату за ліцензію за кожен новий аналізований рецепт. Однак іноді вам може знадобитися оновити дані про харчування для вже поданого рецепту, якщо ви, наприклад, втратили дані про харчування. Подання безпосередньо рецепта буде вважатися аналізом нового рецепту, і з вас знову буде стягнуто ліцензійну плату за інформацію про харчування. Щоб уникнути цього, ми впровадили систему, засновану на механізмі Etag HTTP.

По-перше, кожен успішно оброблений рецепт також поверне тег у заголовку відповіді ETag. Це значення слід зберігати разом із рецептом. Потім, під час повторного надсилання рецепта, ви повинні включити значення в заголовок запиту If-None-Match.

Є три можливі результати:

Ви вже використовуєте найновішу версію даних Edamam. Тобто ви вже маєте найновішу версію харчової інформації. У цьому випадку система поверне код стану HTTP 304 - Не змінено. Зверніть увагу, що ви можете примусити переоцінку в цьому випадку (наприклад, якщо ви втратили свої дані), передавши параметр force. Едамам буде знати, що ви вже платите ліцензію за інформацію про харчування за цим рецептом, і плата за вас не буде двічі.
Ми оновили нашу базу даних, рецепт обробляється знову. У цьому випадку ви отримаєте, можливо, оновлені дані про харчування, а також оновлений заголовок ETag. Ви повинні зберегти це нове значення та використовувати його для подальшого повторного надсилання.
Ви подали рецепт, який ви змінили. Оскільки хеш ETag містить “підпис” для вмісту рецепта, система відповість кодом стану HTTP 409 - Конфлікт. Якщо ви використали неправильний ETag, ви можете використовувати правильний код, або якщо рецепт змінився, ви можете повторно надіслати рецепт як новий (тобто без надсилання заголовка If-None-Match).

Приклад підрахунку ліцензій. Ви проаналізували 100 рецептів перший місяць, 50 другий місяць і 1 третій місяць. Перший місяць ви будете платити ліцензійний збір за харчування 100 рецептів, другий місяць - 150 і третій - 151. Якщо ви не проаналізуєте більше жодного рецепта після третього місяця, ви заплатите ліцензійний збір за харчування загалом з 151 рецептів щомісяця після цього.

Приклад запиту POST

Ось приклад використання curl:

Це надішле файл recipe.json на обробку.

Ось вміст файлу recipe.json:

Відповідь

Код статусу HTTP Тип вмісту Тип Опис

200 Добре	application/json	Рецепт	Об’єкт рецепта, що містить кількість порцій (вихід), загальну калорійність рецепта (калорії), вміст поживних речовин за типом поживної речовини (totalNutrients, totalDaily), класифікацію дієти та здоров’я (dietLabels, healthLabels)
404 Не знайдено	текст/html	HTML	Вказану URL-адресу не знайдено або її не вдалось отримати
422 Неопрацьована сутність	текст/html	HTML	Не вдалося проаналізувати рецепт або отримати інформацію про поживні речовини
555	текст/html	HTML	Рецепт з недостатньою якістю для правильної обробки

Приклад відповіді

Тут ви можете завантажити зразок відповіді з даними про харчування на рівні інгредієнтів

Рецепт

Примітка: Залежно від плану API, за допомогою якого отримуються дані рецептів, може бути присутня лише підмножина полів. Детальніше див. В описі конкретного плану.

опис типу поля

урі	рядок	Ідентифікатор онтології
урожайність	ціле число	Кількість порцій
калорій	плавати	Загальна енергія, ккал
всього Поживні речовини	Інформація про поживні речовини [*]	Загальна кількість поживних речовин
totalDaily	Інформація про поживні речовини [*]	% добового значення
дієта етикетки	перерахувати []	Дієтичні ярлики: «збалансований», «з високим вмістом білка», «з високим вмістом клітковини», «з низьким вмістом жиру», «з низьким вмістом вуглеводів», «з низьким вмістом натрію»
ярлики здоров’я	перерахувати []	Етикетки охорони здоров’я: “веганські”, “вегетаріанські”, “без молочних продуктів”, “з низьким вмістом цукру”, “з низьким вмістом жиру”, “без цукру”, “без жиру”, “без глютену”, “без пшениці "

Докладнішу інформацію щодо “Визначень харчових етикеток” див. У таблиці внизу цього документа

Інформація про поживні речовини

опис типу поля

урі	рядок	Ідентифікатор онтології
етикетці	рядок	Відобразити ярлик
кількість	плавати	Кількість зазначених одиниць
од	рядок	Одиниці

Інгредієнт

Тип поля Опис

foodId	рядок	Ідентифікатор їжі
кількість	плавати	Кількість зазначеної міри
міра	Виміряйте	Виміряйте
вага	плавати	Загальна вага, г.
їжа	Їжа	Їжа

Аналіз тексту їжі

Шлях: https://api.edamam.com/api/nutrition-data

Витягує інформацію з короткого неструктурованого тексту їжі - зазвичай це рядок інгредієнтів і повертає:
- Структуровані дані для тексту - кількість, міра та продукти харчування, якщо такі є
- Дієта, здоров'я та алерген етикетки для тексту
- Завдяки вбудованій функції реєстрації їжі це дозволяє змінити контекст. Наприклад, "рис" зазвичай відповідає сирому рису, тоді як функція реєстрації їжі на ньому буде відповідати готовому до вживання "вареному рису"

Запит на аналіз тексту їжі

Ви будете використовувати запит GET, щоб подати інгредієнт.

Параметр Обов’язковий тип Опис

app_id	так	Рядок	Ваш 3-масштабний ідентифікатор програми
app_key	так	Рядок	Ваш ключ програми 3scale (зверніть увагу, app_id/app_key - це впорядкована пара)
дієтичний тип	ні	Рядок	Коли встановлено значення типу харчування = реєстрація, вона включає функцію реєстрації їжі
інгр	так	Рядок	Інгредієнт (не забудьте URL -кодувати!)

API повертає харчовий аналіз для зазначеного тексту їжі.

Приклад запиту GET

Як приклад, скажімо, ми хочемо витягти інформацію з тексту „одне велике яблуко”. Ви завжди повинні включати кількість та міру, якщо хочете отримати харчування для лінії. В іншому випадку ви отримаєте лише їжу. Тоді нам потрібно URL -код цей рядок. У цьому випадку це означає просто замінити пробіли на% 20, тому він стає “одним% 20великим% 20яблуком”. Зверніть увагу, що лапки не є частиною рядка.

Також важливо зазначити, що розбивка тексту на їжу, міру, кількість доступна лише для планів, де увімкнено функцію «Видобування їжі та кількості». Будь ласка, зверніться до сторінки плану API для отримання детальної інформації.

Ось приклад використання curl:

Якщо ви використовуєте функцію контексту реєстрації продуктів, це змінить відповідь NLP наступним чином
- Ви можете подавати товари без кількості. Ми спробуємо зрівняти їх і призначити їм кількість на основі очікуваного розміру порції
- Підбиратимуться лише ті продукти, які готові до безпосереднього споживання - жодного сирого м’яса, сирої сировини та овочів, які, наприклад, потребують приготування
- Edamam може обробляти лише окремі предмети та лише дві складові речі - наприклад, «курка» або «рис І курка». Переконайтесь, що URL-адреса правильно закодована

Відповідь

Код статусу HTTP Тип вмісту Тип Опис

200 Добре	application/json	Рецепт	Об’єкт рецепта, що містить кількість порцій (вихід), загальну калорійність рецепта (калорії), вміст поживних речовин за типом поживної речовини (totalNutrients, totalDaily), класифікацію дієти та здоров’я (dietLabels, healthLabels)
404 Не знайдено	текст/html	HTML	Вказану URL-адресу не знайдено або її не вдалось отримати
422 Неопрацьована сутність	текст/html	HTML	Не вдалося проаналізувати рецепт або отримати інформацію про поживні речовини
555	текст/html	HTML	Рецепт з недостатньою якістю для правильної обробки

Приклад відповіді

Завжди намагайтеся включати кількість та міру в запити, тобто подайте "одне велике яблуко"

Унікальний текст їжі/ідентифікаційна лінія, повторне подання та кількість ліцензій

Як тільки ви подаєте лінію інгредієнтів через API, ви починаєте платити щомісячну плату за ліцензію за кожну нову лінію аналізованих інгредієнтів. Однак іноді вам може знадобитися оновити дані про харчування для вже поданої лінії інгредієнтів, якщо ви, наприклад, втратили дані про харчування. Безпосередня подача інгредієнтської лінії вважатиметься аналізом нової лінійки інгредієнтів, і з вас знову буде стягнуто ліцензійну плату за інформацію про харчування. Щоб уникнути цього, ми впровадили систему, засновану на механізмі Etag HTTP.

По-перше, кожен успішно оброблений рядок інгредієнта також поверне тег у заголовку відповіді ETag. Це значення слід зберігати разом із лінією інгредієнтів. Потім, під час повторного надсилання рядка інгредієнта, слід включити значення в заголовок запиту If-None-Match.

Є три можливі результати:

Ви вже використовуєте найновішу версію даних Edamam. Тобто ви вже маєте найновішу версію харчової інформації. У цьому випадку система поверне код стану HTTP 304 - Не змінено. Зверніть увагу, що ви можете примусити переоцінку в цьому випадку (наприклад, якщо ви втратили свої дані), передавши параметр force. Едамам буде знати, що ви вже платите ліцензію за інформацію про поживність цієї лінії інгредієнтів, і з вас не стягуватиметься плата двічі.
Ми оновили нашу базу даних, лінія інгредієнтів обробляється знову. У цьому випадку ви отримаєте, можливо, оновлені дані про харчування, а також оновлений заголовок ETag. Ви повинні зберегти це нове значення та використовувати його для подальшого повторного надсилання.
Надіслану вами лінію інгредієнтів ви змінили. Оскільки хеш ETag містить “підпис” для текстового вмісту, система відповість кодом стану HTTP 409 - Конфлікт. Якщо ви використали неправильний ETag, ви можете використати правильний код, або якщо текст/рядок ідентифікатора змінився, ви можете повторно надіслати рядок інгредієнта як новий (тобто без надсилання заголовка If-None-Match).

Приклад підрахунку ліцензій. Ви проаналізували 1000 ліній інгредієнтів перший місяць, 500 другий місяць і 10 третій місяць. Перший місяць ви будете платити ліцензійну плату за харчування 1000 ліній інгредієнтів, другий місяць 1500 і третій 1510. Якщо після третього місяця ви більше не проаналізуєте жодної лінії інгредієнтів, ви заплатите ліцензійну плату за харчування щомісяця щомісяця 1510 інгредієнтів.

Код назви NTR Одиниця виміру NTR Код назви

CA	Кальцій	мг	ENERC_KCAL	Енергія	ккал
CHOCDF	Вуглеводи	g	NIA	Ніацин (B3)	мг
ХОЛ	Холестерин	мг	P	Фосфор	мг
ВІДОМІ	Мононенасичений	g	ПРОКНТ	Білок	g
ФАПУ	Поліненасичені	g	RIBF	Рибофлавін (В2)	мг
ЦУКР	Цукри	g	ЦУКР .додано	Цукри, додані	g
ТУР	Жир	g	FASAT	Насичений	g
FATRN	Транс	g	ТОФФА	Вітамін Е	мг
ІП	Залізо	мг	VITA_RAE	Вітамін А	æg
FIBTG	Клітковина	g	VITB12	Вітамін В12	æg
FOLDFE	Фолат (еквівалент)	æg	FOLFD	Фолієва кислота (їжа)	æg
К	Калій	мг	VITC	Вітамін С	мг
MG	Магній	мг	VITD	Вітамін D	æg
НС	Натрію	мг	ВІТК1	Вітамін К	æg
VITB6A	Вітамін В6	мг	ТІА	Тіамін (B1)	мг

h1. Визначення харчової етикетки

Етикетки харчування поділяються як на рецепти, так і на продукти. Вони призначаються Edamam на основі інгредієнтів, що містяться на етикетці продуктів харчування для продуктів CPG, та основних інгредієнтів кожного рецепта рецептів.

Типи

Складені типи описані з точки зору їх представлення JSON.

В описах використовуються такі позначення:

integer, float та string - це примітивні типи JavaScript, цілі числа, float та string, відповідно
enum означає поле рядка, яке приймає значення лише з попередньо визначеного діапазону (діапазон вказується там, де це необхідно)
T [] означає масив об'єктів типу T
T [*] означає об'єкт (асоціативна карта), кожне поле (елемент) якого має тип T .