API Documentation

Contents

Authentication

All API requests require authentication using an API key. You can create API keys in your API Keys dashboard.

API Key in Header

Include your API key in the X-API-Key header of your requests:

GET /api/v1/emissions-factors
X-API-Key: your-api-key

API Key as Query Parameter

Alternatively, you can include your API key as a query parameter:

GET /api/v1/emissions-factors?api_key=your-api-key
Security Note: Sending the API key as a query parameter is less secure because it may be logged in server logs or browser history. We recommend using the header method when possible.

Verify API Key

You can verify if your API key is valid and retrieve information about it using this endpoint:

Endpoint

GET /api/verify-key

Example Request

GET /api/verify-key
X-API-Key: your-api-key

Example Response (Valid Key)

{
  "valid": true,
  "key_name": "Production API Key",
  "created_at": "2025-04-22T18:30:00.000Z",
  "last_used": "2025-04-22T19:15:30.000Z",
  "user": {
    "username": "acme_corp",
    "email": "api@acme-corp.com"
  },
  "subscription": {
    "plan": "professional",
    "status": "active"
  }
}

Example Response (Invalid Key)

{
  "valid": false,
  "error": "Invalid API key"
}
Use Case: This endpoint is useful to verify API key validity before making other API calls, or to check the subscription status and rate limits associated with your key.

Emissions Factors

Endpoint

GET /api/v1/emissions-factors

Query Parameters

Parameter Type Description
q string Search term for item name
source string Filter by source (e.g., 'DEFRA')
region string Filter by region (e.g., 'UK')
year integer Filter by year
scope string Filter by scope (e.g., '1', '2', '3')
category string Filter by category name

Example Request

GET /api/v1/emissions-factors?q=electricity&source=DEFRA&year=2023
X-API-Key: your-api-key

Example Response

{
  "data": [
    {
      "item": "Electricity",
      "category": "Energy",
      "source": "DEFRA",
      "region": "UK",
      "year": 2023,
      "scope": "2",
      "value": 0.19338,
      "unit": "kg CO2e/kWh",
      "confidence": 0.95,
      "version": "1.0"
    }
  ]
}

Categories

Endpoint

GET /api/v1/categories

Example Response

{
  "data": [
    {
      "id": 1,
      "name": "Energy"
    },
    {
      "id": 2,
      "name": "Transport"
    }
  ]
}

Items

Endpoint

GET /api/v1/items

Query Parameters

Parameter Type Description
category_id integer Filter by category ID
q string Search term for item name

Example Request

GET /api/v1/items?category_id=1
X-API-Key: your-api-key

Example Response

{
  "data": [
    {
      "id": 1,
      "name": "Electricity",
      "category_id": 1,
      "category": {
        "id": 1,
        "name": "Energy"
      }
    },
    {
      "id": 2,
      "name": "Natural Gas",
      "category_id": 1,
      "category": {
        "id": 1,
        "name": "Energy"
      }
    }
  ]
}

Sources

Endpoint

GET /api/v1/sources

Example Response

{
  "data": ["DEFRA", "EPA", "GHG Protocol"]
}

Regions

Endpoint

GET /api/v1/regions

Example Response

{
  "data": ["UK", "US", "EU", "Global"]
}

Scopes

Endpoint

GET /api/v1/scopes

Example Response

{
  "data": ["1", "2", "3"]
}

Years

Endpoint

GET /api/v1/years

Example Response

{
  "data": [2023, 2022, 2021, 2020, 2019]
}

Rate Limits

API requests are subject to rate limiting based on your subscription plan:

Plan Rate Limit
Basic 100 requests per day
Professional 1,000 requests per day
Enterprise Unlimited

Rate limit information is returned in the response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1682678400

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

Status Code Description
200 - OK Request succeeded
400 - Bad Request Invalid request parameters
401 - Unauthorized Authentication failed
403 - Forbidden API key does not have permission to access the resource
404 - Not Found Resource not found
429 - Too Many Requests Rate limit exceeded
500 - Internal Server Error Server error

Error Response Format

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid parameter: year must be an integer.",
    "status": 400
  }
}