Kcalbase API (1.0.0)

Download OpenAPI specification:

Kcalbase: support@kcalbase.com URL: https://docs.kcalbase.com License: Preview terms

UK-first food and nutrition data with gram weights on every serving.

Read-only API over the Kcalbase store. All routes are GET under /v1. Send your key as Authorization: Bearer kb_live_.... Every response carries X-Request-Id, X-Kcalbase-Data-Version and X-Kcalbase-Data-Updated; metered responses add the four X-Kcalbase-Quota-* headers. Open-layer rows carry an attribution block your app must render (ODbL, Open Food Facts; OGL, CoFID).

foods

Search, lookup and batch lookup

Full-text search with typo tolerance

Authorizations:

bearerAuth

query Parameters

q required	string [ 1 .. 100 ] characters Search text. Trimmed; case-insensitive.
limit	integer [ 1 .. 25 ] Default: 10 Clamped into range.
cursor	string Opaque cursor from `next_cursor`; bound to the same `q`.

Responses

Response samples

200
400
401
429

Content type

application/json

{"query": "string",
"matched": "exact",
"results": [{"id": "string",
"layer": "open",
"food_type": "generic",
"name": "string",
"brand": "string",
"barcode": "string",
"categories": ["string"
],
"allergens": ["string"
],
"basis": "g",
"per_100": {"energy_kcal": 0,
"protein_g": 0,
"carbs_g": 0,
"sugars_g": 0,
"fat_g": 0,
"saturated_fat_g": 0,
"fibre_g": 0,
"salt_g": 0
},
"servings": [{"id": "string",
"label": "string",
"quantity": 0,
"unit": "string",
"grams": 0,
"grams_source": "published",
"is_default": true,
"nutrients": {"energy_kcal": 0,
"protein_g": 0,
"carbs_g": 0,
"sugars_g": 0,
"fat_g": 0,
"saturated_fat_g": 0,
"fibre_g": 0,
"salt_g": 0
}
}
],
"images": {"front": {"url": "http://example.com",
"licence": "string",
"attribution": "string"
},
"nutrition": {"url": "http://example.com",
"licence": "string",
"attribution": "string"
}
},
"quality": {"gate_status": "pass",
"flags": ["string"
],
"completeness": 100
},
"provenance": {"source": "string",
"source_url": "http://example.com",
"source_id": "string",
"licence": "ODbL-1.0",
"retrieved_at": "2019-08-24T14:15:22Z",
"source_modified_at": "string"
},
"attribution": {"required": true,
"text": "string",
"url": "http://example.com"
},
"updated_at": "2019-08-24T14:15:22Z"
}
],
"next_cursor": "string"
}

Thin typeahead suggestions

Authorizations:

bearerAuth

query Parameters

q required	string [ 2 .. 100 ] characters
limit	integer [ 1 .. 10 ] Default: 8

Responses

Response samples

200
400
401
429

Content type

application/json

{"query": "string",
"suggestions": [{"id": "string",
"name": "string",
"brand": "string",
"default_serving": "string"
}
]
}

Lookup by EAN/UPC/GTIN

Authorizations:

bearerAuth

path Parameters

code

required

string^[0-9]{8}$|^[0-9]{12,14}$

8, 12, 13 or 14 digits; normalised to GTIN-14.

Responses

Response samples

200
400
401
404
429

Content type

application/json

{"id": "string",
"layer": "open",
"food_type": "generic",
"name": "string",
"brand": "string",
"barcode": "string",
"categories": ["string"
],
"allergens": ["string"
],
"basis": "g",
"per_100": {"energy_kcal": 0,
"protein_g": 0,
"carbs_g": 0,
"sugars_g": 0,
"fat_g": 0,
"saturated_fat_g": 0,
"fibre_g": 0,
"salt_g": 0
},
"servings": [{"id": "string",
"label": "string",
"quantity": 0,
"unit": "string",
"grams": 0,
"grams_source": "published",
"is_default": true,
"nutrients": {"energy_kcal": 0,
"protein_g": 0,
"carbs_g": 0,
"sugars_g": 0,
"fat_g": 0,
"saturated_fat_g": 0,
"fibre_g": 0,
"salt_g": 0
}
}
],
"images": {"front": {"url": "http://example.com",
"licence": "string",
"attribution": "string"
},
"nutrition": {"url": "http://example.com",
"licence": "string",
"attribution": "string"
}
},
"quality": {"gate_status": "pass",
"flags": ["string"
],
"completeness": 100
},
"provenance": {"source": "string",
"source_url": "http://example.com",
"source_id": "string",
"licence": "ODbL-1.0",
"retrieved_at": "2019-08-24T14:15:22Z",
"source_modified_at": "string"
},
"attribution": {"required": true,
"text": "string",
"url": "http://example.com"
},
"updated_at": "2019-08-24T14:15:22Z"
}

Batch lookup by barcodes and/or ids (up to 50; metered at one request per 10 items)

Authorizations:

bearerAuth

query Parameters

barcodes	string Comma-separated barcodes.
ids	string Comma-separated Kcalbase ids.

Responses

Response samples

200
400
401
429

Content type

application/json

{"found": [{"id": "string",
"layer": "open",
"food_type": "generic",
"name": "string",
"brand": "string",
"barcode": "string",
"categories": ["string"
],
"allergens": ["string"
],
"basis": "g",
"per_100": {"energy_kcal": 0,
"protein_g": 0,
"carbs_g": 0,
"sugars_g": 0,
"fat_g": 0,
"saturated_fat_g": 0,
"fibre_g": 0,
"salt_g": 0
},
"servings": [{"id": "string",
"label": "string",
"quantity": 0,
"unit": "string",
"grams": 0,
"grams_source": "published",
"is_default": true,
"nutrients": {"energy_kcal": 0,
"protein_g": 0,
"carbs_g": 0,
"sugars_g": 0,
"fat_g": 0,
"saturated_fat_g": 0,
"fibre_g": 0,
"salt_g": 0
}
}
],
"images": {"front": {"url": "http://example.com",
"licence": "string",
"attribution": "string"
},
"nutrition": {"url": "http://example.com",
"licence": "string",
"attribution": "string"
}
},
"quality": {"gate_status": "pass",
"flags": ["string"
],
"completeness": 100
},
"provenance": {"source": "string",
"source_url": "http://example.com",
"source_id": "string",
"licence": "ODbL-1.0",
"retrieved_at": "2019-08-24T14:15:22Z",
"source_modified_at": "string"
},
"attribution": {"required": true,
"text": "string",
"url": "http://example.com"
},
"updated_at": "2019-08-24T14:15:22Z"
}
],
"missing": ["string"
]
}

Lookup by Kcalbase id

Authorizations:

bearerAuth

path Parameters

id

required

string^[0-9A-HJKMNP-TV-Z]{26}$

Responses

Response samples

200
400
401
404
429

Content type

application/json

{"id": "string",
"layer": "open",
"food_type": "generic",
"name": "string",
"brand": "string",
"barcode": "string",
"categories": ["string"
],
"allergens": ["string"
],
"basis": "g",
"per_100": {"energy_kcal": 0,
"protein_g": 0,
"carbs_g": 0,
"sugars_g": 0,
"fat_g": 0,
"saturated_fat_g": 0,
"fibre_g": 0,
"salt_g": 0
},
"servings": [{"id": "string",
"label": "string",
"quantity": 0,
"unit": "string",
"grams": 0,
"grams_source": "published",
"is_default": true,
"nutrients": {"energy_kcal": 0,
"protein_g": 0,
"carbs_g": 0,
"sugars_g": 0,
"fat_g": 0,
"saturated_fat_g": 0,
"fibre_g": 0,
"salt_g": 0
}
}
],
"images": {"front": {"url": "http://example.com",
"licence": "string",
"attribution": "string"
},
"nutrition": {"url": "http://example.com",
"licence": "string",
"attribution": "string"
}
},
"quality": {"gate_status": "pass",
"flags": ["string"
],
"completeness": 100
},
"provenance": {"source": "string",
"source_url": "http://example.com",
"source_id": "string",
"licence": "ODbL-1.0",
"retrieved_at": "2019-08-24T14:15:22Z",
"source_modified_at": "string"
},
"attribution": {"required": true,
"text": "string",
"url": "http://example.com"
},
"updated_at": "2019-08-24T14:15:22Z"
}

Service health and data freshness (unmetered, no key)

Responses

Response samples

200

Content type

application/json

{"ok": true,
"open_foods": 0,
"core_foods": 0,
"data_version": 0,
"data_updated": "string"
}

This document (unmetered, no key)

Responses

Response samples

200

Content type

application/json

{ }

Kcalbase API (1.0.0)

foods

Full-text search with typo tolerance

Authorizations:

query Parameters

Responses

Response samples

Thin typeahead suggestions

Authorizations:

query Parameters

Responses

Response samples

Lookup by EAN/UPC/GTIN

Authorizations:

path Parameters

Responses

Response samples

Batch lookup by barcodes and/or ids (up to 50; metered at one request per 10 items)

Authorizations:

query Parameters

Responses

Response samples

Lookup by Kcalbase id

Authorizations:

path Parameters

Responses

Response samples

meta

Service health and data freshness (unmetered, no key)

Responses

Response samples

This document (unmetered, no key)

Responses

Response samples

This document as YAML (unmetered, no key)

Responses