API docs

Product metadata

This section describes various metadata that may be available for products.

Metadata availability and contents may vary depending on the product type. At the moment several types of metadata may be available:

Generic objects:

metadata.generic — generic metadata

Generic metadata may contain these fields:

NameDescriptionCount
generic.ageGroups A list of strings, representing the age groups that the product is targeted for. Possible values: infant (0-1 years), toddler (1-3), child (3-12), teen (12-18), adult (18-60), senior (60+). 
{
    "ageGroups": ["child", "teen"]
}
 3 261 (0% of products)
generic.colors Product color, an array of objects. See Product colors for the list of supported values and an example. 9 364 323 (14% of products)
generic.contributors Product contributors (book authors, music performers, etc.), a list of objects. Each contributor object has following attributes:
  • names — "lang" → "contributor name / title" mapping
  • type — contributor type, string, one of the following:
    • author — book author
    • narrator — audio book narrator
    • translator — book translator
    • artist — artist (for music recordings: composer / musician etc.)
    • music_group — music group / band
    • choir — choir / chorus / large vocal ensemble
    • orchestra — large instrumental ensemble
 10 916 988 (16% of products)
generic.dimensions Product and packaging dimensions information, an object: 
{
    // Product dimensions, if available
    "product": {
        // Can contain "width", "height", "depth" and / or "length" attributes
        // Each attribute is a Measurement object
        "width": {
            "equals": {
                "value": 9.5, // Dimension value
                "unit": "cm"  // Supported values: ["cm"]
            }
        },
        // ...
        "depth": {
            "equals": {
                "value": 19.5,
                "unit": "cm"
            }
        }
    },
    // Packaging dimensions, if available
    "packaging": {
        // ... same structure as for product dimensions
    }
}
 8 992 768 (13% of products)
generic.genderFit Gender fit of a product, string. Can be one of the following values: male, female, unisex. 1 604 050 (2% of products)
generic.ingredients Product ingredients or materials. See Product ingredients for detailed information. 5 913 887 (9% of products)
generic.manufacturerCode Manufacturer product code, string. 10 175 606 (15% of products)
generic.numberOfItems Number of individual items that are included in the product as sold, a Measurement object. 889 161 (1% of products)
generic.power Product power (in watts), a Measurement object. 
{
    "equals": {
        "value": 750,
        "unit": "watts"
    }
}
 5 627 (0% of products)
generic.storageConditions An object, describing product storage conditions. Can contain the following keys:
  • shelfLife — product shelf life, a Measurement object. Valid units: hour, day, week, month, year.
  • temperature — recommended product storage temperature, a Measurement object. Valid unit: degree_celsius. Often contains ranges (lessThan and greaterThan).
  • humidity — recommended product storage humidity, a Measurement object. Valid unit: percent. Often contains ranges (lessThan and greaterThan).
  • recommendations — other recommendations, an array of strings. Possible values: cool_place, dark_place, dry_place, avoid_direct_sunlight, refrigerate_after_opening, do_not_freeze, room_temperature.
"storageConditions" : {
    "shelfLife" : {
        "equals" : {
            "value" : "6",
            "unit" : "month"  // supported values: ["hour", "day", "week", "month", "year"]
        }
    },
    "temperature" : {
        "greaterThan" : {
              "value" : "5",
              "unit" : "degree_celsius"
        },
        "lessThan" : {
            "value" : "22",
            "unit" : "degree_celsius"
        }
    },
    "humidity" : {
        "lessThan" : {
            "value" : "75",
            "unit" : "percent"
        }
    },
    "recommendations": ["avoid_direct_sunlight", "refrigerate_after_opening"]
}
 208 725 (0% of products)
generic.volume Product volume information, a Measurement object. 
{
    "equals": {
        "value": 100,  // Volume value, float
        "unit": "ml"   // Supported values: ["ml"]
    }
}
 780 794 (1% of products)
generic.weight Product weight information, a mapping of net (for net weight), gross (for gross weight) or unknown (when we lack information whether it's net or gross weight) to a Measurement object: 
{
    "net": {
        "equals": {
            "value": 150.0,  // Weight value, float
            "unit": "grams"  // Supported values: ["grams"]
        }
    },
    "gross": {
        "equals": {
            "value": 200.0,
            "unit": "grams"
        }
    }
}
 4 121 795 (6% of products)

An example of generic metadata:

{
    // ...
    "product": {
        "metadata": {
            "generic": {
                "manufacturerCode": "PRODUCT-CODE-123",
                "colors": ["white"],
                "contributors": [
                    {
                        "names": {
                            "en": "John Smith"
                        },
                        "type": "author"
                    }
                ]
            }
        }
    }
}

metadata.apparel — shoes, clothing and other apparel products

Apparel products metadata may contain following fields:

NameDescriptionCount
apparel.sizes The apparel_sizes field is an array containing one or more Measurement objects. Each object specifies a size using one of the following units:
  • size_label — for standard clothing size labels (XXS, XS, S, M, L, XL, XXL, XXXL, XXXXL, one_size)
  • eu_shoe_size — for European shoe sizes
  • us_shoe_size — for US shoe sizes
A garment with size XS: 
[{
    "equals": {"value": "XS", "unit": "size_label"}
}]
A pair of shoes with US and EU sizes: 
[{
    "equals": {"value": "8", "unit": "us_shoe_size"}
}, {
    "equals": {"value": "41", "unit": "eu_shoe_size"}
}]
 320 596 (10% of apparel products)

metadata.electric — electric products

Electric products metadata may contain these fields:

NameDescriptionCount
electric.voltage Product voltage (in volts), a Measurement object. 
{
    "equals": {
        "value": 1.5,
        "unit": "volts"
    }
}
 28 101 (0% of products)

metadata.externalIds — product ids in external sources

External ids metadata may contain these fields:

NameDescriptionCount
externalIds.amazonAsin Amazon Standard Identification Number, string. 1 268 160 (2% of products)

An example of external ids metadata:

{
    // ...
    "product": {
        "metadata": {
            "externalIds": {
                "amazonAsin": "AMAZONASIN"
            }
        }
    }
}

metadata.food — food items and beverages

Food metadata may contain these fields:

NameDescriptionCount
food.nutrimentsPer100Grams Food nutriments information. See Food nutriments for detailed information. 1 322 360 (56% of food products)
food.nutriScore Product Nutri-Score, an object: 
{
    "score": 1,   // Nutri-Score, an integer
    "grade": "B"  // Nutri-Score letter grade (from "A" to "E")
}
 791 640 (34% of food products)

An example of food metadata:

{
    // ...
    "product": {
        "metadata": {
            "food": {
                "nutrimentsPer100Grams": {
                    "fat": {
                        "equals": {
                            "value": 1.0,
                            "unit": "grams"
                        }
                    },
                    "proteins": {
                        "equals": {
                            "value": 12.0,
                            "unit": "grams"
                        }
                    },
                    "energy": {
                        "equals": {
                            "value": 654,
                            "unit": "kcal"
                        }
                    },
                },
                "nutriScore": {
                    "score": 1,
                    "grade": "B"
                }
            }
        }
    }
}

metadata.printBook — print books

Print book metadata may contain these fields:

NameDescriptionCount
printBook.numPages Number of pages in print book, integer. 8 353 942 (74% of print books)
printBook.bisacCodes BISAC codes of a print book, list of strings. 1 240 064 (11% of print books)
printBook.bindingType Book binding type, one of strings: hardcover, paperback. 9 345 708 (82% of print books)

An example of print book metadata:

{
    // ...
    "product": {
        "metadata": {
            "printBook": {
                "numPages": 123,
                "bisacCodes": ["FIC027110"],
                "bindingType": "paperback"
            }
        }
    }
}

metadata.media — books, music and other media products

Media products metadata, relevant for digital or physical books, newspapers, magazines, music and sound recordings. May contain following fields:

NameDescriptionCount
media.publicationYear Media product publication or release year, integer. In case of re-issues that use the same barcode, this is the year of the first publication. For on-demand publications, this is the year of the original publication. 13 792 694 (83% of media products)

An example of media metadata:

{
    // ...
    "product": {
        "metadata": {
            "media": {
                "publicationYear": 1990
            }
        }
    }
}

Measurement object

Measurement represents various measurements (weights, sizes, amounts, dimensions) for metadata properties values.

It is a mapping of one or several measures (currently supported: equals, lessThan, greaterThan) to value objects. Each value object consists of value field that holds a numeric or a string measurement and unit field, containing the unit in which this measurement is represented.

// Precise measurement example
{
    "equals": {
        "value": 12.5,
        "unit": "ml"
    }
}

// Measurement range example
{
    "greaterThan": {
        "value": 10,
        "unit": "mg"
    },
    "lessThan": {
        "value": 20,
        "unit": "mg"
    }
}

// String measurement value example
{
    "equals": {
        "value": "XS",
        "unit": "size_label"
    }
}
© 2024 EAN-DB DOO, support@ean-db.com
Terms of Service · Privacy policy · Cookie policy · Consent Preferences