API docs

Products 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.externalIds — product ids in external sources

External ids metadata may contain these fields:

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

An example of external ids metadata:

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <!-- ... -->
    <product>
        <!-- ... -->
        <metadata>
            <externalIds>
                <amazonAsin>AMAZONASIN</amazonAsin>
            </externalIds>
        </metadata>
    </error>
</response>

metadata.generic — generic metadata

Generic metadata may contain these fields:

Name	Description	Count
generic.weightGrams	Product weight in grams, integer.	8 673 909 (18% of products)
generic.manufacturerCode	Manufacturer product code, string.	7 395 217 (15% of products)
generic.color	Product color, one of strings: `beige`, `black`, `blue`, `bronze`, `brown`, `chrome`, `dark_blue`, `gold`, `gray`, `green`, `ivory`, `khaki`, `light_blue`, `magenta_fuchsia`, `multi`, `orange`, `pink`, `purple`, `red`, `silver`, `transparent`, `white`, `yellow`.	6 188 622 (13% of products)
generic.materials	Product materials, a list of strings. Possible string values: `acryl`, `aluminum`, `artificial_leather`, `brass`, `bronze`, `cardboard`, `ceramic`, `cotton`, `copper`, `elastane_lycra_spandex`, `glass`, `latex`, `leather`, `mdf`, `metal`, `neoprene`, `nylon`, `paper`, `plastic`, `plywood`, `polyester`, `polyethylene`, `polypropylene`, `polyurethane`, `pvc`, `rubber`, `silver`, `silicone`, `stainless_steel`, `steel`, `vinyl`, `viscose`, `wood`, `wool`.	3 098 610 (6% of products)
generic.contributors	Product contributors (book authors, musicCD performers, etc.), a list of objects. Each contributor 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.	11 317 669 (23% of products)

An example of generic metadata:

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <!-- ... -->
    <product>
        <!-- ... -->
        <metadata>
            <generic>
                <weightGrams>123</weightGrams>
                <manufacturerCode>PRODUCT-CODE-123</manufacturerCode>
                <color>white</color>
                <materials>
                    <material>plastic</material>
                </materials>
                <contributors>
                    <contributor>
                        <names>
                            <name lang="en">John Smith</name>
                        </names>
                        <type>author</type>
                    </contributor>
                </contributors>
            </generic>
        </metadata>
    </error>
</response>

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

Food metadata may contain these fields:

Name	Description	Count
food.nutrimentsPer100Grams.fatGrams	Fat content, grams per 100 grams.	1 062 801 (54% of food products)
food.nutrimentsPer100Grams.proteinsGrams	Proteins content, grams per 100 grams.	1 063 960 (54% of food products)
food.nutrimentsPer100Grams.carbohydratesGrams	Carbohydrates content, grams per 100 grams.	1 059 602 (53% of food products)
food.nutrimentsPer100Grams.energyKCal	Energy value, kcal per 100 grams.	1 041 390 (53% of food products)
food.nutrimentsPer100Grams.cholesterolMg	Cholesterol content, milligrams per 100 grams.	282 844 (14% of food products)
food.nutrimentsPer100Grams.sodiumMg	Sodium (Na) content, milligrams per 100 grams.	835 679 (42% of food products)
food.nutrimentsPer100Grams.potassiumMg	Potassium (K) content, milligrams per 100 grams.	150 872 (8% of food products)
food.nutrimentsPer100Grams.calciumMg	Calcium (Ca) content, milligrams per 100 grams.	290 150 (15% of food products)

An example of food metadata:

{
    // ...
    "product": {
        // ...
        "metadata": {
            "food": {
                "nutrimentsPer100Grams": {
                    "fatGrams": 1.0,
                    "proteinsGrams": 12.0,
                    "carbohydratesGrams": 34.5,
                    "energyKCal": 654.0
                }
            }
        }
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <!-- ... -->
    <product>
        <!-- ... -->
        <metadata>
            <food>
                <nutrimentsPer100Grams>
                    <fatGrams>1.0</fatGrams>
                    <proteinsGrams>12.0</proteinsGrams>
                    <carbohydratesGrams>34.5</carbohydratesGrams>
                    <energyKCal>654.0</energyKCal>
                </nutrimentsPer100Grams>
            </food>
        </metadata>
    </error>
</response>

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 395 917 (77% of print books)
printBook.publishedYear	Book publication year, integer.	8 018 257 (84% of print books)
printBook.bisacCodes	BISAC codes of a print book, list of strings.	1 255 947 (13% of print books)
printBook.bindingType	Book binding type, one of strings: `hardcover`, `paperback`.	7 723 879 (80% of print books)

An example of print book metadata:

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <!-- ... -->
    <product>
        <!-- ... -->
        <metadata>
            <printBook>
                <numPages>123</numPages>
                <publishedYear>2021</publishedYear>
                <bisacCodes>
                    <bisacCode>FIC027110</bisacCode>
                </bisacCodes>
                <bindingType>paperback</bindingType>
            </printBook>
        </metadata>
    </error>
</response>

metadata.musicCD — for music CDs

Music CD metadata may contain these fields:

Name	Description	Count
musicCD.releasedYear	Year of first music CD release, integer.	1 353 479 (97% of music CDs)
musicCD.numberOfDiscs	Number of discs, integer.	360 132 (26% of music CDs)

An example of music CD metadata:

{
    // ...
    "product": {
        // ...
        "metadata": {
            "musicCD": {
                "releasedYear": 1990,
                "numberOfDiscs": 1
            }
        }
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <!-- ... -->
    <product>
        <!-- ... -->
        <metadata>
            <musicCD>
                <releasedYear>1990</releasedYear>
                <numberOfDiscs>1</numberOfDiscs>
            </musicCD>
        </metadata>
    </error>
</response>