Eaternity API
The Eaternity Database API is a Web Service that calculates the Climate Score (CO₂ equivalents), the Vita Score and other environmental footprints of recipes, restaurants, and ingredients dynamically.
It includes daily changing information on origin, seasonality and other factors in the calculation.
Key Features
- Climate Score: Calculate CO₂ equivalents for recipes and ingredients
- Vita Score: Nutritional quality rating (A-E scale)
- Environmental Metrics: Water footprint, rainforest impact, animal welfare, seasonality, and local sourcing ratings
- Forecast: AI-powered sales predictions for kitchens
Terms & Conditions
By accessing the APIs, you accept Eaternity's Terms & Conditions.
Authentication
- HTTP: Basic Auth
Authentication
The Eaternity API uses HTTP Basic Authentication. Your API key is the username - no password is required.
How it works
- Enter your API key in the Username field below
- The password field is not used (leave empty or ignore)
- The browser automatically encodes credentials as Base64 in the
Authorizationheader
The resulting header format is: Authorization: Basic <base64(apikey:)>
Test API Key
Contact info@eaternity.ch to request API access.
cURL Example
# The -u flag handles Base64 encoding automatically
# The colon after the API key indicates empty password
curl -u YOUR_API_KEY: \
-H "Content-Type: application/json" \
https://co2.eaternity.ch/api/kitchens
Programmatic Usage
// JavaScript/Node.js
const apiKey = 'YOUR_API_KEY';
const auth = btoa(apiKey + ':'); // Base64 encode "apikey:"
fetch('https://co2.eaternity.ch/api/kitchens', {
headers: {
'Authorization': 'Basic ' + auth,
'Content-Type': 'application/json'
}
});
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | basic |
Contact Eaternity Team: info@eaternity.ch
License Proprietary
Advanced Information
Localization
The API is designed such that one request may contain information about an object (e.g. a recipe or a supply) in multiple languages. Every JSON field which is subject to localization has a language array as value:
{
"language": "de",
"value": "Kürbisrisotto"
}
The language field must contain one of the ISO 639-1 alpha-2 codes.
ID Generation
The IDs of recipes, kitchens and supplies can be generated in two different ways:
- POST request: ID is generated by Eaternity
- PUT request: You provide your own ID in the URL (recommended)
The ID can be any alphanumeric value following this regex pattern: [-a-zA-Z0-9+&@#/%?=~_|!:,.;]*[-a-zA-Z0-9+&@#/%=~_|]
Notes on the Format
- The API accepts JSON in requests and returns JSON in all responses
- Only UTF-8 character encoding is supported
- All requests must be encrypted through SSL
SSL & Server Name Indication (SNI)
Since Eaternity uses distributed servers, the IP-address of the service changes and is shared between different applications.
To make SSL work, the desired hostname (co2.eaternity.ch) needs to be specified with every request according to the SNI specification:
openssl s_client -connect co2.eaternity.ch:443 -servername eaternity.ch
We recommend whitelisting the Cloudflare root certificate cloudflare_origin_rsa.pem.
HTTP Status Codes
Success Codes
| Code | Description |
|---|---|
| 200 | Request succeeded |
| 201 | Resource created successfully |
| 202 | Request accepted for async processing (Products) |
| 204 | Resource deleted successfully (no content) |
Client Error Codes
| Code | Description |
|---|---|
| 400 | Bad request - malformed JSON or invalid content |
| 401 | No authorization - valid API key not provided |
| 403 | Forbidden - kitchen not authorized for calculations |
| 404 | Not found - requested resource does not exist |
| 405 | Method not allowed |
Server Error Codes
| Code | Description | Action |
|---|---|---|
| 500 | Server Error | Retry the request, or contact support |
Validation Error Codes
| Code | Description | Action |
|---|---|---|
| 422 | Request Validation Error — request does not match the expected schema (e.g., integer where string was expected) | Fix the request format |
Processing Error Codes (Eaternity-specific)
These custom status codes indicate specific processing issues:
| Code | Name | Description | Action |
|---|---|---|---|
| 601 | Manual Matching Missing | An ingredient ID is not yet manually matched in the Eaternity Database | Retry once daily |
| 602 | No Automatic Match | At least one ingredient name could not be automatically matched in the Eaternity Database | Retry once daily or try a different ingredient name |
| 610 | Missing Required Property | A required resource property was not given in the request | Provide the required field |
| 611 | Wrong Property Value | A resource property was not provided according to the documentation — wrong format or invalid value | Fix the property value |
| 612 | Sub-Recipe Not Found | A referenced recipe was not provided in this or a previous request | Include sub-recipe in batch or create it first |
| 670 | Recipe Has No Ingredients | A sub-recipe was referenced with a positive quantity but has no ingredients itself | Add ingredients to the sub-recipe |
Additional implementation-specific codes
The following codes are returned by the calculation engine for specific processing failures. They are not documented in the canonical API specification but may appear in practice.
| Code | Name | Description | Action |
|---|---|---|---|
| 671 | Missing LCA Inventory | No life cycle inventory found for ingredient | Contact support with term details |
| 672 | Missing Nutrients | No nutrient data found for ingredient | Contact support with term details |
| 673 | Failed Amount Estimation | Could not estimate ingredient amount | Check declaration format |
| 674 | Failed Ingredient Splitter | Could not parse ingredient declaration | Simplify ingredient declaration |
| 675 | Unknown Unit | Ingredient unit not recognized | Use standard units (gram, liter) |
| 678 | CO2 Calculation Failed | Cannot calculate CO2 value | Check ingredient data completeness |
| 679 | VitaScore Calculation Failed | Cannot calculate VitaScore | Check nutrient data availability |
| 680 | Environment Score Failed | Cannot calculate environment score | Check environmental data availability |
Handling 6xx Errors
The 6xx error codes are specific to Eaternity's calculation system:
-
601/602: Occur when an ingredient cannot be matched to the Eaternity database. The matching process runs daily, so retry after 24 hours or try a more common ingredient name.
-
610/611: These relate to missing or invalid request properties. Check the request against the API documentation.
-
612: Verify that sub-recipes are created before referencing them, or include them in the same batch request.
-
670: Ensure sub-recipes contain at least one ingredient before referencing them.
-
671-680: These indicate calculation engine issues. Check that ingredient declarations are properly formatted and use standard units.
Choosing Your API
The Eaternity APIs serve different user groups with distinct requirements.
| Feature | Eaternity API | LCA API |
|---|---|---|
| Primary Users | Restaurants, Food Manufacturers, ERP Systems | LCA Practitioners, Researchers |
| Use Case | Operational sustainability tracking | Scientific LCA research |
| Data Granularity | Recipe/menu level | Full supply chain detail |
| Batch Processing | Optimized for high volume | Optimized for precision |
Choose the Eaternity API if you are a restaurant or food service operation, integrating with ERP or food management software, tracking menu sustainability metrics, or generating environmental reports for operations.
Choose the LCA API if you are an LCA practitioner or researcher, conducting detailed supply chain analysis, requiring full lifecycle transparency, or working with research-grade environmental data.
These APIs serve different purposes. There is no need to migrate between them — choose the one that best fits your use case.