API documentation

Product ingredients metadata

Here is an example of product ingredients metadata:

{
    "product": {
        "metadata": {
            "generic": {
                "ingredients": [
                    {
                        "groupName": null,
                        "ingredientsGroup": [
                            {
                                "originalNames": { "en": "Concentrated Apple Juice" },
                                "id": "apples",
                                "properties": {
                                    "processing": ["concentrated", "juice"]
                                },
                                "isVegan": true,
                                "isVegetarian": true
                            },
                            {
                                "originalNames": { "en": "Sugar" },
                                "id": "sugar",
                                "amount": {
                                    "lessThan": {"value": 1.0, "unit": "percent"}
                                }
                            },
                            {
                                "originalNames": {
                                    "en": "Disodium Guanylate And Inosinate"
                                },
                                "subIngredients": [
                                    {
                                        "id": "e627", 
                                        "canonicalNames": {"en": "Disodium Guanylate (E627)"}
                                    },
                                    {
                                        "id": "e631", 
                                        "canonicalNames": {"en": "Disodium Inosinate (E631)"}
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        }
    }
}

Let's break this down a bit.

Product ingredients are split into groups. This is relevant for some products that consist of several items — in this case the ingredient of each item will be put into a separate group (we’ll see an example later on). In the example above there's only one group (and it has a default groupName = null).

Each ingredient may have these attributes:

Attribute name	Description
originalNames	Ingredient names as found on product packaging, "lang" → "name" mapping. This attribute may not exist, for example if we can't find an individual entry for this ingredient or when it is inferred from the parts of the text (like the two last ingredients in the example).
id	Ingredient identifier (if the ingredient exists in our database).
canonicalNames	Canonical names of the identified ingredient ("lang" → "name" mapping). You may rely on the fact that either `originalNames` or `canonicalNames` (or both) exist for each ingredient.
properties	Indredient properties, a mapping of property group name to a list of string properties. For a full list of properties and property groups see Ingredient properties.
amount	Ingredient amount, a Measurement object. Supported unit values: `["percent", "grams", "mg", "gramsPer100Grams", "gramsPer100Ml"]`.
isVegan	`True` if the ingredient is suitable for vegans, `false` otherwise. May be omitted if this data is unavailable.
isVegetarian	`True` if the ingredient is suitable for vegetarians, `false` otherwise. May be omitted if this data is unavailable.
subIngredients	Array of sub-ingredients for complex ingredients.
externalIds	A map, containing references to this ingredient in various external sources: • `cosIng` — Ingredient identifier in European Cosmetics ingredient database • `wikidata` — Ingredient identifier in Wikidata knowledge base

Now, let's look at an example with several groups of ingredients:

{
    "product": {
        "metadata": {
            "generic": {
                "ingredients": [
                    {
                        "groupName": "Hair Mask with Intrabond Hair Repairing Complex",
                        "ingredientsGroup": [
                            {
                                "originalNames": {"en": "Water"},
                                "id": "water",
                                "isVegan": true, "isVegetarian": true
                            },
                            {
                                "originalNames": { "en": "Behentrimonium Chloride" },
                                "id": "behentrimonium-chloride"
                            }
                            // ...
                        ]
                    },
                    {
                        "groupName": "Lightest & Brightest Powder Bleach",
                        "ingredientsGroup": [
                            {
                                "originalNames": {"en": "Potassium Persulfate"},
                                "id": "e922",
                                "isVegan": true, "isVegetarian": true
                            },
                            {
                                "originalNames": {"en": "Sodium Silicate"},
                                "id": "e550-i",
                                "isVegan": true, "isVegetarian": true
                            }
                        ]
                    }
                ]
            }
        }
    }
}

As you can see, this product has two groups of ingredients, each group corresponds to a certain item within a product and is described by its groupName attribute (in this case, Hair Mask with Intrabond Hair Repairing Complex and Lightest & Brightest Powder Bleach).