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:

metadata.externalIds — product ids in external sources
metadata.generic — generic metadata
metadata.food — for food items, beverages and baby food
metadata.printBook — for print books
metadata.musicCD — for music CDs
metadata.media — for media products
metadata.electric — for electric products

Generic objects:

Amount

metadata.externalIds — product ids in external sources

External ids metadata may contain these fields:

Name	Description	Count
externalIds.amazonAsin	Amazon Standard Identification Number, string.	1 279 272 (2% of products)

An example of external ids metadata:

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

metadata.generic — generic metadata

Generic metadata may contain these fields:

Name	Description	Count
generic.ingredients	Product ingredients or materials. See Product ingredients for detailed information.	5 591 238 (9% of products)
generic.contributors	Product contributors (book authors, musicCD 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, `artist` — artist (for music recordings: composer / musician etc.), `music_group` — music group / band, `choir` — choir / chorus / large vocal ensemble, `orchestra` — large instrumental ensemble.	10 939 440 (17% 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 an Amount object: `{ "net": { "equals": { "value": 150.0, // Weight value, float "unit": "grams" // Supported values: ["grams"] } }, "gross": { "equals": { "value": 200.0, "unit": "grams" } } }`	3 688 206 (6% of products)
generic.volume	Product volume information, an Amount object: `{ "equals": { "value": 100, // Volume value, float "unit": "ml" // Supported values: ["ml"] } }`	331 500 (1% 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 an Amount 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 } }`	7 336 603 (12% of products)
generic.manufacturerCode	Manufacturer product code, string.	12 370 907 (20% of products)
generic.colors	Product color, an array of strings. See Product colors for the list of supported values and an example.	7 995 275 (13% of products)

An example of generic metadata:

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

metadata.food — for food items, beverages and baby food

Food metadata may contain these fields:

Name	Description	Count
food.nutrimentsPer100Grams	Food nutriments information. See Food nutriments for detailed information.	1 176 343 (50% 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") }`	787 002 (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 — for print books

Print book metadata may contain these fields:

Name	Description	Count
printBook.numPages	Number of pages in print book, integer.	7 197 651 (71% of print books)
printBook.bisacCodes	BISAC codes of a print book, list of strings.	1 243 592 (12% of print books)
printBook.bindingType	Book binding type, one of strings: `hardcover`, `paperback`.	8 303 496 (82% of print books)

An example of print book metadata:

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

metadata.musicCD — for music CDs

Music CD metadata may contain these fields:

Name	Description	Count
musicCD.numberOfDiscs	Number of discs, integer.	358 967 (25% of music CDs)

An example of music CD metadata:

{
    // ...
    "product": {
        "metadata": {
            "musicCD": {
                "numberOfDiscs": 1
            }
        }
    }
}

metadata.media — for media products

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

Name	Description	Count
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.	11 559 976 (78% of media products)

An example of media metadata:

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

metadata.electric — for electric products

Electric products metadata may contain these fields:

Name	Description	Count
electric.voltage	Product voltage, an Amount object. `{ "equals": { "value": 1.5, "unit": "volts" } }`	21 030 (0% of products)

An example of electric product metadata:

{
    // ...
    "product": {
        "metadata": {
            "electric": {
                "voltage": {
                    "equals": {
                        "value": 1.5,
                        "unit": "volts"
                    }
                }
            }
        }
    }
}

Amount object

Amount represents various amounts in metadata properties.

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 the numeric amount and unit field, containing the unit in which this amount is represented.

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

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