Connect
Connect API is our RESTful service for subscribing and querying sustainability data for specific products. Subscriptions can be used together with our webhook service.
Base url: https://connect.consupedia.com/api/v2/Authenticate
To authorize your requests, you'll need to use an API key. The key should be included in the header of your requests as follows:
Header:
Key: X-API-KEY
Value: [your_api_key]
To make a sample cURL request using the provided authorization, replace [your_api_key] with your actual API key:
cURL example
curl -X GET 'https://connect.consupedia.com/api/v2/...' -H 'X-API-KEY: your_api_key'Python example
import requests
url = 'https://connect.consupedia.com/api/v2/...'
headers = {
'X-API-KEY': 'your_api_key'
}
response = requests.get(url, headers=headers)
Javascript example
const axios = require('axios');
const url = 'https://connect.consupedia.com/api/v2/...';
const headers = {
'X-API-KEY': 'your_api_key'
};
axios.get(url, { headers })
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error(error);
});/subscribe/
A set of endpoints to manage your subscriptions.
GET /subscribe/account
https://connect.consupedia.com/api/v2/subscribe/accountGet information about your subscriptions.
cURL example
curl -X GET 'https://connect.consupedia.com/api/v2/subscribe/account' -H 'X-API-KEY: your_api_key'Response example
{
"status": "active",
"client": "Demo Company Inc.",
"subscriptions": {
"current_count": 123,
"max_limit": 1000
}
}/products/
Endpoints to get sustainability fields of subscribed products.
POST /subscribe/
https://connect.consupedia.com/api/v2/subscribe/
This endpoint enables the subscription of products. The request should have a JSON object in the body.
Request body
The JSON formatted body (Content-type application/json) should by an Array of products.
A product is required to have at least gtin field:
[
{
"gtin": "123456789010"
},
{
"gtin": "923456789010"
}
];If you want to supply more product data, the following fields may also be added:
[
{
"gtin": STRING,
"name": STRING,
"ingredients": STRING,
"origin": STRING,
"category": STRING,
"brand": STRING,
"size": FLOAT,
"size_unit": STRING,
"image_url": TEXT,
"price": FLOAT,
"price_currency": STRING,
"is_eco": INTEGER (1 or 0),
"certificates": STRING
}
];Here is the available fields in table form with short descriptions:
| Field Name | Description | Type | Max length | Example |
|---|---|---|---|---|
| gtin | Global Trade Item Number | STRING | 14 | "0000000000001" |
| name | Name of the product | STRING | 255 | "Ekologisk Äppeljuice" |
| ingredients | List of ingredients in the product seperated with commas. Procent of ingredient of total product is added with parenthesis after ingredient name. | STRING | 1000 | "Äpple (60%), vatten (25%), socker (15%)" |
| origin | Country of origin of the product | STRING | 50 | "Spanien" |
| category | Product category | STRING | 50 | "Juice & fruktdryck" |
| brand | Brand name of the product | STRING | 100 | "JuiceCo" |
| size | Size of the product | FLOAT | N/A | 1.5 |
| size_unit | Unit of measurement for the size (e.g. "ml", "g") | STRING | 10 | "g" |
| image_url | URL for an image of the product | TEXT | N/A | "https://example.com/juice.jpg" |
| price | Price of the product | FLOAT | N/A | 5.99 |
| price_currency | Currency of the price (e.g. "USD", "EUR", "SEK") | STRING | 3 | "SEK" |
| is_eco | Whether the product is eco-friendly (1 or 0) | INTEGER | N/A | 1 |
| certificates | List of certificate names of the product | STRING | 1000 | "Krav,Rainforest Alliance" |
Supported Languages
For best results, add text data in Swedish or English.
Update a subscription with more data
If you got more/changed product information and would like to update your subscription, use the same method and body as a new subscription. If the subscription already exists, the subscription will be updated.
cURL example
curl -X POST 'https://connect.consupedia.com/api/v2/subscribe/' \
-H 'X-API-KEY: your_api_key' \
-H 'Content-Type: application/json' \
-d '[
{
"gtin": "123456789010"
},
{
"gtin": "923456789010"
}
]'Response example
{
"status": "success",
"message": "Products subscribed",
"client": "Consupedia",
"productsSubscribed": 1,
"unknownProductsSubscribed": 1,
"productsSkipped": 0
}POST /subscribe/more/add
https://connect.consupedia.com/api/v2/subscribe/more/add
This endpoint enables the subscription of products with rich product data. The request should have a JSON object in the body.
Request body
The JSON formatted body (Content-type application/json) should be a product represented as a single object.
A product is required to have at least gtin or client_identifier field:
{
"gtin": "12345678901011",
}
If you want to supply more product data, the following fields may also be added:
{
"gtin": STRING,
"client_identifier": STRING,
"name": STRING,
"information_provider_gln": STRING,
"category": STRING,
"subcategory": INTEGER,
"brand_name": STRING,
"external_name": STRING,
"functional_name": STRING,
"packaging_label": STRING,
"country_of_origin": STRING,
"provenance_statement": STRING,
"raw_material_origin": STRING,
"packaging_type": STRING,
"packaging_material": STRING,
"packaging_material_quantity": FLOAT,
"packaging_material_unit": STRING,
"ingredients": TEXT,
"size": STRING,
"alcohol_percentage": FLOAT,
"preparation_state": STRING,
"nutrient_basis_quantity": FLOAT,
"nutrient_basis_unit": STRING,
"quantity_energy_kj": FLOAT,
"quantity_energy_kcal": FLOAT,
"quantity_fat": FLOAT,
"quantity_part_saturated_fat": FLOAT,
"quantity_part_monounsaturated_fat": FLOAT,
"quantity_part_polyunsaturated_fat": FLOAT,
"quantity_carbohydrate": FLOAT,
"quantity_part_sugars": FLOAT,
"quantity_part_polyols": FLOAT,
"quantity_part_starch": FLOAT,
"quantity_fibre": FLOAT,
"quantity_protein": FLOAT,
"quantity_salt":FLOAT,
"secondary_preparation_state": STRING,
"secondary_nutrient_basis_quantity": FLOAT,
"secondary_nutrient_basis_unit": STRING,
"secondary_quantity_energy_kj": FLOAT,
"secondary_quantity_energy_kcal": FLOAT,
"secondary_quantity_fat": FLOAT,
"secondary_quantity_part_saturated_fat": FLOAT,
"secondary_quantity_part_monounsaturated_fat": FLOAT,
"secondary_quantity_part_polyunsaturated_fat": FLOAT,
"secondary_quantity_carbohydrate": FLOAT,
"secondary_quantity_part_sugars": FLOAT,
"secondary_quantity_part_polyols": FLOAT,
"secondary_quantity_part_starch": FLOAT,
"secondary_quantity_fibre": FLOAT,
"secondary_quantity_protein": FLOAT,
"secondary_quantity_salt":FLOAT,
"marketing_message": TEXT,
"image_original": STRING,
"image_high_res": STRING,
"image_low_res": STRING
}Here is the available fields in table form with short descriptions:
| Field Name | Description | Type | Max length | Example |
|---|---|---|---|---|
| gtin | Global Trade Item Number | STRING | 14 | 12345678901234 |
| client_identifier | Identifier assigned by the client | STRING | 50 | CI123456 |
| name | Product name | STRING | 255 | Chocolate Bar |
| information_provider_gln | Global Location Number of the information provider | STRING | 13 | 4000001000001 |
| category | Product category | STRING | 255 | Alcoholic Beverages |
| subcategory | Product subcategory | INTEGER | 10820 | |
| brand_name | Brand name of the product | STRING | 100 | Sweet Treats |
| external_name | Product name used in external systems | STRING | 255 | ChocoBar |
| functional_name | Functional name of the product | STRING | 255 | Snack |
| packaging_label | Packaging label information | STRING | 255 | Recyclable packaging |
| country_of_origin | Country where the product is originated | STRING | 255 | US |
| provenance_statement | Statement of product's provenance | STRING | 255 | Made in the USA |
| raw_material_origin | Origin of the raw materials | STRING | 255 | Cocoa beans from Ghana |
| packaging_type | Type of packaging | STRING | 255 | Box |
| packaging_material | Material used for packaging | STRING | 255 | Cardboard |
| packaging_material_quantity | Quantity of packaging material | FLOAT | 10.5 | |
| packaging_material_unit | Unit of measurement for packaging material | STRING | 10 | g |
| ingredients | List of ingredients | STRING | 1000 | Cocoa mass, sugar, cocoa butter, emulsifier (soy lecithin), natural vanilla flavor |
| size | Product size | STRING | 50 | 100g |
| alcohol_percentage | Alcohol percentage, if applicable | FLOAT | 0.0 | |
| preparation_state | State of the product before consumption | STRING | 255 | Ready-to-eat |
| nutrient_basis_quantity | Quantity for nutrient basis | FLOAT | 100.0 | |
| nutrient_basis_unit | Unit of measurement for nutrient basis | STRING | 10 | g |
| quantity_energy_kj | Energy in kilojoules | FLOAT | 2230.0 | |
| quantity_energy_kcal | Energy in kilocalories | FLOAT | 533.0 | |
| quantity_fat | Fat content | FLOAT | 31.0 | |
| quantity_part_saturated_fat | Saturated fat content | FLOAT | 0.3 | |
| quantity_part_monounsaturated_fat | Monounsaturated fat content | FLOAT | 0.1 | |
| quantity_part_polyunsaturated_fat | Polyunsaturated fat content | FLOAT | 4.0 | |
| quantity_carbohydrate | Carbohydrate content | FLOAT | 51.0 | |
| quantity_part_sugars | Sugar content | FLOAT | 47.0 | |
| quantity_part_polyols | Polyol content | FLOAT | 0.0 | |
| quantity_part_starch | Starch content | FLOAT | 4.0 | |
| quantity_fibre | Fibre content | FLOAT | 3.0 | |
| quantity_protein | Protein content | FLOAT | 7.0 | |
| quantity_salt | Salt content | FLOAT | 0.1 | |
| secondary_preparation_state | Secondary state of the product before consumption | STRING | 255 | |
| secondary_nutrient_basis_quantity | Secondary quantity for nutrient basis | FLOAT | ||
| secondary_nutrient_basis_unit | Secondary unit of measurement for nutrient basis | STRING | 10 | |
| secondary_quantity_energy_kj | Secondary energy in kilojoules | FLOAT | ||
| secondary_quantity_energy_kcal | Secondary energy in kilocalories | FLOAT | ||
| secondary_quantity_fat | Secondary fat content | FLOAT | ||
| secondary_quantity_part_saturated_fat | Secondary saturated fat content | FLOAT | ||
| secondary_quantity_part_monounsaturated_fat | Secondary monounsaturated fat content | FLOAT | ||
| secondary_quantity_part_polyunsaturated_fat | Secondary polyunsaturated fat content | FLOAT | ||
| secondary_quantity_carbohydrate | Secondary carbohydrate content | FLOAT | ||
| secondary_quantity_part_sugars | Secondary sugar content | FLOAT | ||
| secondary_quantity_part_polyols | Secondary polyol content | FLOAT | ||
| secondary_quantity_part_starch | Secondary starch content | FLOAT | ||
| secondary_quantity_fibre | Secondary fibre content | FLOAT | ||
| secondary_quantity_protein | Secondary protein content | FLOAT | ||
| secondary_quantity_salt | Secondary salt content | FLOAT | ||
| marketing_message | Marketing message for the product | STRING | 1000 | Indulge in the rich taste of our premium chocolate bar made with the finest cocoa beans. |
| image_original | URL of the original product image | STRING | 500 | https://example.com/images/chocolate_bar_original.jpg |
| image_high_res | URL of the high-resolution product image | STRING | 500 | https://example.com/images/chocolate_bar_high_res.jpg |
| image_low_res | URL of the low-resolution product image | STRING | 500 | https://example.com/images/chocolate_bar_low_res.jpg |
Supported Languages
For best results, add text data in Swedish or English.
Update a subscription with more data
If you got more/changed product information and would like to update your subscription, use the same method and body as a new subscription. If the subscription already exists, the subscription will be updated.
cURL example
curl -X POST 'https://connect.consupedia.com/api/v2/subscribe/add/more' \
-H 'X-API-KEY: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
"gtin": "123456789010"
}'
Response example
{
"status": "success",
"action": "subscription_created",
"client": "Demo Company Inc.",
"subscriptions": {
"current_count": 124,
"max_limit": 2000
}
}DELETE /subscribe/{gtin}
End a product subscription by calling /subscribe/:gtin with the DELETE method.
https://connect.consupedia.com/api/v2/subscribe/:gtinPath Parameters
- id: Global Trade Item Number (GTIN)
- Description: The unique identifier for the product.
- Type: String
- Example: "0000000000001"
cURL example
curl --location --request DELETE 'https://connect.consupedia.com/api/v2/subscribe/123456789010' --header 'X-API-KEY: your_api_key'DELETE /subscribe/unsubscribeById/{client_identifier}
End a product subscription by client_identifier.
https://connect.consupedia.com/api/v2/subscribe/unsubscribeById/:client_identifierPath Parameters
- client_identifier: Your own identifier associated with a subscribed product.
- Description: The unique identifier for the product.
- Type: String
- Example: "abc0000000000001"
cURL example
curl --location --request DELETE 'https://connect.consupedia.com/api/v2/subscribe/unsubscribeById/abc-123' --header 'X-API-KEY: your_api_key'Response
{
"status": "success",
"message": "Product unsubscribed",
"action": "product_unsubscribed",
"client": "Consupedia"
}/webhook/
This endpoint exposes services to trigger webhook requests. To specify your webhook's url, contact tech-support@consupedia.com. The response of these services will always be a single product object in json. .
GET /webhook/trigger/
Trigger a random product to be sent to your webhook url. The product is sent with a POST request to the webhook.
https://connect.consupedia.com/api/v2/webhook/triggercURL example
curl --location --request GET 'https://connect.consupedia.com/api/v2/webhook/trigger' --header 'X-API-KEY: your_api_key'Response example
{
"status": "success",
"action": "webhook_triggered",
"message": "A random product has been sent."
}Example of the body of the POST request sent the webhook url
{
"id": "05425007723373-7314060000003", // client identifier if sent with the subscription
"gtin": "5425007723373",
"climateScore": 40,
"CO2e": 2.5,
"novaScore": 1,
"nutriScore": "E",
"healthScore": 15,
"antibioticsResistanceScore": 81,
"overconsumptionRisk": "",
"socialJusticeScore": 63,
"equalityScore": 95,
"workerRightsScore": 85,
"animalProtectionScore": null,
"childLaborScore": 100,
"biodiversityScore": 82,
"pesticidesUseScore": 69,
"fertilizersUseScore": 5,
"landUseScore": null,
"waterScore": 32,
"transportScore": 89,
"isEco": 1
}