Introduction

Welcome to the Emissions Ecoinvent API documentation. This API provides access to comprehensive Life Cycle Impact Assessment (LCIA) data from the Ecoinvent database.

Authentication

All API requests require authentication using an API key. Include your API key in the x-api-key header.

curl -X GET ${API_BASE_URL}/ecoinvent/datasets \
  -H "x-api-key: your_api_key_here"

const response = await fetch('${API_BASE_URL}/ecoinvent/datasets', {
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
const data = await response.json();

import requests

response = requests.get(
    '${API_BASE_URL}/ecoinvent/datasets',
    headers={'x-api-key': 'your_api_key_here'}
)
data = response.json()

Rate Limiting

API requests are limited per user based on their account settings. Default limits:

• Rate Limit: 100 requests
• Time Window: 60 seconds

Rate limit headers are included in each response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640000000

Pagination

List endpoints support pagination using query parameters:

Paginated Response Format

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1000,
    "totalPages": 20
  }
}

Error Handling

The API implements comprehensive error handling with detailed error responses to help you quickly identify and resolve issues.

HTTP Status Codes

Error Response Format

All error responses follow a consistent format with the following fields:

{
  "statusCode": 404,
  "timestamp": "2025-12-29T10:30:45.123Z",
  "path": "/ecoinvent/activities/invalid-uuid",
  "method": "GET",
  "error": "Not Found",
  "message": "Activity not found with UUID: invalid-uuid"
}

Error Response Fields

Common Error Examples

400 Bad Request - Missing Required Parameter

{
  "statusCode": 400,
  "timestamp": "2025-12-29T10:30:45.123Z",
  "path": "/ecoinvent/activities/:uuid",
  "method": "GET",
  "error": "Bad Request",
  "message": "Activity UUID is required"
}

400 Bad Request - Invalid Input Validation

{
  "statusCode": 400,
  "timestamp": "2025-12-29T10:30:45.123Z",
  "path": "/logs",
  "method": "GET",
  "error": "Bad Request",
  "message": "Limit must be a number between 1 and 1000"
}

404 Not Found - Resource Not Found

{
  "statusCode": 404,
  "timestamp": "2025-12-29T10:30:45.123Z",
  "path": "/ecoinvent/datasets/non-existent-id",
  "method": "GET",
  "error": "Not Found",
  "message": "Dataset not found with ID: non-existent-id"
}

401 Unauthorized - Invalid API Key

{
  "statusCode": 401,
  "timestamp": "2025-12-29T10:30:45.123Z",
  "path": "/ecoinvent/datasets",
  "method": "GET",
  "error": "Unauthorized",
  "message": "Invalid API key"
}

500 Internal Server Error - Database Error

{
  "statusCode": 500,
  "timestamp": "2025-12-29T10:30:45.123Z",
  "path": "/ecoinvent/emissions/search",
  "method": "GET",
  "error": "Internal Server Error",
  "message": "Database error while searching emissions"
}

Input Validation

The API performs comprehensive input validation on all requests:

• Required Parameters: All required path and query parameters are validated
• Data Types: Parameters are type-checked and automatically converted when possible
• Range Validation: Numeric parameters (e.g., page, limit) are validated against min/max values
• Format Validation: UUIDs, dates, and other formatted values are validated
• Empty Values: Empty strings and null values are rejected for required fields

Error Logging

All errors are automatically logged on the server with:

• Full error stack traces for debugging
• Request context (path, method, user)
• Timestamp and error severity
• Database connection status