Version: 1.0

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.

---

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:

1. POST request: ID is generated by Eaternity
2. 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

Processing Error Codes (Eaternity-specific)

These custom status codes indicate specific processing issues:

Code	Name	Description	Action
500	Server Error	Internal server error	Contact support
602	Missing Matching	Ingredient name not yet matched in Eaternity Database	Retry once daily or use different name
611	Kitchen Not Found	Specified kitchen/group does not exist	Verify kitchen ID
612	Sub-Recipe Not Found	Ingredient links to non-existing recipe	Include sub-recipe in batch or create it first
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

Status Code 670

Status code 670 (empty recipe) exists in the codebase but is currently disabled. Recipes without ingredients return status 200 instead.

Handling 6xx Errors

The 6xx error codes are specific to Eaternity's calculation system:

• 602: Occurs 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.

• 611/612: These relate to kitchen and sub-recipe references. Verify that the kitchen ID exists and that sub-recipes are created before referencing them.

• 671-675: These indicate data processing issues. Check that ingredient declarations are properly formatted and use standard units.

• 678-680: These indicate calculation failures. Ensure all required data is available for the requested calculations.

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

1. Enter your API key in the Username field below
2. The password field is not used (leave empty or ignore)
3. The browser automatically encodes credentials as Base64 in the Authorization header

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

URL: https://eaternity.org/contact

License

Proprietary