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 271 065 (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 889 258 (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, `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 894 699 (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 693 761 (6% of products)
generic.volume	Product volume information, an Amount object: `{ "equals": { "value": 100, // Volume value, float "unit": "ml" // Supported values: ["ml"] } }`	386 240 (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 269 958 (11% of products)
generic.manufacturerCode	Manufacturer product code, string.	12 315 667 (19% of products)
generic.colors	Product color, an array of strings. See Product colors for the list of supported values and an example.	8 026 932 (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 161 365 (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") }`	783 484 (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 189 223 (71% of print books)
printBook.bisacCodes	BISAC codes of a print book, list of strings.	1 241 870 (12% of print books)
printBook.bindingType	Book binding type, one of strings: `hardcover`, `paperback`.	8 272 884 (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.	351 076 (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 503 511 (79% 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 (in volts), an Amount object. `{ "equals": { "value": 1.5, "unit": "volts" } }`	22 200 (0% of products)
electric.power	Product power (in watts), an Amount object. `{ "equals": { "value": 750, "unit": "watts" } }`	4 838 (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"
    }
}