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.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"
    }
}
28 163 (0% of products)

An example of electric product metadata:

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

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 269 268 (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.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. 8 750 780 (14% 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 883 365 (17% 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
    }
}
9 042 632 (14% of products)
generic.ingredients Product ingredients or materials. See Product ingredients for detailed information. 5 910 231 (9% of products)
generic.manufacturerCode Manufacturer product code, string. 12 368 571 (19% of products)
generic.power Product power (in watts), an Amount object.
{
    "equals": {
        "value": 750,
        "unit": "watts"
    }
}
7 540 (0% of products)
generic.volume Product volume information, an Amount object:
{
    "equals": {
        "value": 100,  // Volume value, float
        "unit": "ml"   // Supported values: ["ml"]
    }
}
495 954 (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 an Amount object:
{
    "net": {
        "equals": {
            "value": 150.0,  // Weight value, float
            "unit": "grams"  // Supported values: ["grams"]
        }
    },
    "gross": {
        "equals": {
            "value": 200.0,
            "unit": "grams"
        }
    }
}
3 736 610 (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.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 173 224 (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")
}
784 107 (33% 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 269 194 (72% of print books)
printBook.bisacCodes BISAC codes of a print book, list of strings. 1 241 328 (12% of print books)
printBook.bindingType Book binding type, one of strings: hardcover, paperback. 8 272 303 (82% of print books)

An example of print book metadata:

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

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 725 010 (79% of media products)

An example of media metadata:

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

metadata.musicCD — for music CDs

Music CD metadata may contain these fields:

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

An example of music CD metadata:

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

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"
    }
}