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 327 (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 708 499 (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 935 112 (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 692 901 (6% of products)
generic.volume	Product volume information, an Amount object: `{ "equals": { "value": 100, // Volume value, float "unit": "ml" // Supported values: ["ml"] } }`	386 084 (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 319 871 (12% of products)
generic.manufacturerCode	Manufacturer product code, string.	12 370 567 (20% of products)
generic.colors	Product color, an array of strings. See Product colors for the list of supported values and an example.	8 017 083 (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 177 099 (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 349 (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 254 (71% of print books)
printBook.bisacCodes	BISAC codes of a print book, list of strings.	1 243 669 (12% of print books)
printBook.bindingType	Book binding type, one of strings: `hardcover`, `paperback`.	8 298 596 (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.	359 373 (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 553 995 (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 884 (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"
    }
}