API товаров доступно по адресу https://ean-db.com/api/v2/product/{barcode}, где {barcode} — это шаблон для реального штрих-кода EAN / UPC / ISBN.
Успешный запрос, например такой:
curl -X GET -H 'Authorization: Bearer HERE_GOES_YOUR_JWT_TOKEN' -H 'Accept: application/json' \
https://ean-db.com/api/v2/product/1234567890123
возвращает ответ с кодом 200 и объектом ProductResponse в качестве тела.
Обратите внимание, что мы используем заголовок Accept: application/json для указания типа контента JSON в ответе. Другие типы контента не поддерживаются. Если заголовок Accept отсутствует, то по умолчанию используется application/json.
{
"balance": 100, // Ваш текущий баланс (кол-во запросов на счету), целое число
"product": {
"barcode": "1234567890123", // Штрих-код товара, приведённый к канонической форме GTIN-8/12/13/14, строка
"barcodeDetails": {
"type": "EAN-13", // Barcode type: EAN-8, EAN-13, EAN-14 or ISBN
"description": "GS1 US", // Barcode prefix description
"country": "us" // Barcode country (if defined)
},
"titles": {
"en": "Product title", // Названия товара, маппинг "язык" → "название"
"de": "Produktname"
},
// Категории товара, массив объектов (или пустой массив)
"categories": [
{
"id": "3911", // Идентификатор категории из Google product taxonomy, строка
"titles": { // Названия категорий, маппинг "язык" → "название"
"en": "Bath Toys"
}
},
{
"id": "543543",
"titles": {
"en": "Print Books"
}
}
],
// Производитель или бренд товара (если доступен, может быть null)
"manufacturer": {
"id": "manufacturer-id", // Идентификатор производителя / бренда товара (для существующих в базе производителей, может быть null), строка
"titles": { // Названия производителя / бренда товара, маппинг "язык" → "название"
"en": "Manufacturer"
},
"wikidataId": "Q12345" // Идентификатор производителя / бренда товара в [Базе знаний Wikidata](https://wikidata.org) (если существует, может быть null), строка
},
// Другие бренды, имеющие отношение к продукту (дистрибьюторы, коллаборации и пр.), массив объектов (или пустой массив)
"relatedBrands": [{
"id": "related-manufacturer-id",
"titles": {
"en": "Related manufacturer"
},
"wikidataId": "Q12346"
}],
// Изображения товара, массив объектов (или пустой массив)
"images": [
{
"url": "https://ean-db.com/image.jpg", // URL изображения, строка
"isCatalog": true // True, если изображение может быть использовано в каталоге (профессионально снято)
"width": 500, // Image width in pixels
"height": 500 // Image height in pixels
}
],
// Метаданные товара (если доступны, может быть null), подробнее см. <a href="/docs/productMetadata">Метаданные товаров</a>
"metadata": {
"printBook": {
"numPages": 123
},
"media": {
"publicationYear": 2010
}
}
}
}
Формальная структура ответа описана в JSON схеме.
Категории товара (поле categories) представляют собой массив объектов, содержащих идентификатор и название категории. Массив может быть пустым, если информация о категориях товара на данный момент недоступна. Товары категоризированы с использованием Google product taxonomy, более подробная информация об этой системе категоризации — в данной статье.
Поле manufacturer содержит объект с информацией о производителе или бренде товара. Поле может иметь значение null, если в базе нет информации о производителе. В остальных случаях будет присутствовать как минимум поле manufacturer.titles.
Часть производителей являются идентифицированными — в таком случае будет также доступно поле manufacturer.id. В нём содержится постоянный идентификатор производителя, который может быть полезен для устранения неоднозначностей в случае когда различные производители или бренды имеют похожие названия.
relatedBrands содержит информацию о других брендах, которые могут иметь отношение к продукту или быть упомянуты на упаковке (например, дистрибьюторы или коллаборации). Представляет собой массив объектов с той же структурой, как и в поле manufacturer. Все компании / бренды в поле relatedBrands являются идентифицированными (содержат поле id).
В поле images выдаются изображения товара в виде массива объектов, содержащих адрес изображения. Массив может быть пустым, если изображения товара недоступны.
Поле metadata может содержать различные метаданные товара, например вес, пищевые характеристики для продуктов питания или количество страниц для печатных книг (и может иметь значение null, если метаданные отстутствуют). Набор метаданных может отличаться в зависимости от типа товара, подробнее см. в разделе Метаданные товаров.
Ответ с кодом 404 возвращается в случае, если товар с запрошенным штрих-кодом не найден в нашей базе данных. Ваш баланс (количество запросов к API на счету) при этом не уменьшается.
{
"error": {
"code": 404, // Код ошибки, целое число
"description": "Product not found: 9785811264209" // Краткое описание ошибки, строка
},
"balance": 100 // Your current balance (remaining requests), integer
}
Вы можете получить ответ с кодом 403 в следующих случаях:
Заголовок Authorization, содержащий ваш JWT отсутствует или имеет некорректное значение.
В этом случае в поле description ответа об ошибке будет содержаться сообщение JWT is missing or invalid, check Authorization header. Обратитесь к руководству за информацией о том, как получить JWT и корректно передать его в запросе.
Ваш email не был подтверждён.
Подтверждение email обязательно для совершения запросов к API — для этого необходимо перейти по ссылке из письма, присланного вам после регистрации.
В случае данной ошибки поле description будет содержать сообщение Your account is not confirmed, please check your email for confirmation link.
Ваш JWT был отозван (сопровождается сообщением JWT revoked в поле description).
Вы можете отозвать ваш текущий JWT (и запретить дальнейший доступ к API с данным токеном) в настройках аккаунта. Данная ошибка будет возвращаться всякий раз когда вы попытаетесь обратиться к API используя один из отозванных JWT.
Срок действия вашего JWT истёк (сопровождается сообщением JWT expired в поле description).
JWT становится просроченным спустя год с момента его генерации. Если вы встретили данную ошибку, вам необходимо сгенерировать новый JWT в настройках вашего аккаунта и заменить старый JWT на обновлённый.
Ваш баланс (количество запросов к API на счету) исчерпан.
В этом случае поле description будет содержать сообщение Your account balance is empty.
{
"error": {
"code": 403,
"description": "Your account balance is empty" // Или одно из других сообщений об ошибке
}
}
Код ответа 400 сигнализирует о том, что запрошенный вами штрих-код некорректен по той или иной причине (содержит некорректные символы, слишком короткий или длинный и т.д.). Более подробная информация выдаётся в поле description ответа об ошибке.
{
"error": {
"code": 400,
"description": "Invalid barcode: 978581126barcode" // Или одно из других сообщений об ошибке
}
}
Related topics: ProductResponse JSON schema · Billing