Website Carbon Getting Started: API Key & First Request (2026)

Getting started overview

Integrating the Website Carbon API involves a few core steps: signing up for an account, generating an API key, and then using that key to make requests. The API is designed for simplicity, offering a single endpoint to query the carbon footprint of a given URL. This guide provides a structured approach to making your first successful API call and outlines common next steps and troubleshooting tips.

The Website Carbon API operates on a GET request model, returning data in JSON format, which is a standard exchange format for web services, as described by the W3C JSON Data Interchange Standard. Authentication relies on an API key included in your request, which helps secure your access and track usage against your plan limits.

Before proceeding, ensure you have access to a command-line interface (CLI) or a REST client (like Postman or Insomnia) to send HTTP requests. For developers, familiarity with basic HTTP methods and JSON parsing is beneficial.

Create an account and get keys

To begin using the Website Carbon API, you must first create an account on their platform. This process establishes your identity and grants you access to your API key, which is essential for authenticating your requests.

1. Navigate to the API Page: Go to the official Website Carbon API documentation page. This page provides an overview of the API's capabilities and pricing structure.
2. Sign Up: Look for a 'Sign Up' or 'Get Started' button. The platform offers a free tier for up to 100 requests per month, which is suitable for initial testing and development. Follow the prompts to create your account, providing the necessary information such as email and password.
3. Verify Email (if required): Some signup processes include an email verification step. Check your inbox for a confirmation link and follow it to activate your account.
4. Access Dashboard: Once logged in, you will typically be directed to an API dashboard or a developer portal. This area is where you manage your subscription, monitor usage, and, critically, retrieve your API key.
5. Locate API Key: On your dashboard, find the section labeled 'API Key' or 'Developer Credentials'. Your API key will be a unique alphanumeric string. Copy this key and store it securely. Treat your API key like a password; it grants access to your account's API usage.

Website Carbon's API keys are generally tied to your account and plan, dictating your rate limits and available features. The API documentation specifies that keys are used to authenticate requests and manage access levels.

Your first request

With your API key in hand, you can now make your first request to the Website Carbon API. This example uses curl, a common command-line tool for making HTTP requests, which is available on most Unix-like systems and can be installed on Windows. The core API endpoint for checking a website's carbon footprint is straightforward.

API Endpoint: https://api.websitecarbon.com/site

The API expects two parameters: the url of the website you want to analyze and your api_key.

Example Request with cURL

Replace YOUR_API_KEY with the actual API key you obtained from your Website Carbon dashboard, and example.com with the website you wish to analyze.

curl -X GET "https://api.websitecarbon.com/site?url=https://www.apispine.com&api_key=YOUR_API_KEY"

Expected Response Structure (JSON)

A successful request will return a JSON object containing various data points related to the website's carbon footprint. The exact fields may vary slightly, but a typical response includes information such as the website's green status, energy consumption, and carbon emissions. Below is an illustrative example of what you might receive:

{
  "url": "https://www.apispine.com",
  "green": true,
  "bytes": 1234567,
  "cleanerThan": 0.75,
  "co2": {
    "grid": {
      "grams": 1.23,
      "litres": 0.0006
    },
    "renewable": {
      "grams": 0.23,
      "litres": 0.0001
    }
  },
  "timestamp": 1678886400,
  "statistics": {
    "adjustedBytes": 1234567,
    "data": {
      "cdn": 0.1,
      "js": 0.3,
      "css": 0.2,
      "image": 0.4
    }
  },
  "summary": "This website is hosted green and is cleaner than 75% of tested websites."
}

Key fields to note in the response include:

• url: The URL that was analyzed.
• green: A boolean indicating if the website is hosted on renewable energy.
• co2: An object detailing carbon emissions in grams and liters, broken down by grid and renewable energy sources.
• cleanerThan: A percentage indicating how much cleaner this website is compared to others in their database.

For a complete list of response fields and their descriptions, refer to the Website Carbon API reference documentation.

Common next steps

After successfully making your first API call, consider these next steps to further integrate and utilize the Website Carbon API:

1. Error Handling: Implement robust error handling in your application. The API will return standard HTTP status codes (e.g., 400 for bad request, 401 for unauthorized, 429 for rate limit exceeded, 500 for server errors) along with a JSON error body. Understanding these codes is crucial for creating resilient applications, as detailed in general MDN Web Docs on HTTP status codes.
2. Rate Limiting: Review the API's rate limits as specified in the Website Carbon API pricing and documentation. Design your application to respect these limits, potentially using client-side rate limiting or exponential backoff strategies for retries.
3. Integration into Applications: Begin integrating the API into your web or backend applications. This might involve building a dashboard to track the carbon footprint of multiple websites, automating reports, or adding sustainability metrics to a CI/CD pipeline.
4. Explore Paid Tiers: If your usage requirements exceed the free tier's 100 requests per month, explore the paid plans. These plans offer higher request volumes and potentially additional features.
5. Caching: Consider caching API responses for frequently accessed URLs to reduce API calls and improve performance. Website carbon data for a given URL doesn't change frequently, making it a good candidate for caching.
6. Security Best Practices: Always keep your API key secure. Do not hardcode it directly into client-side code, and use environment variables for backend applications.
7. User Interface Development: If you're building a user-facing application, design an intuitive interface to display the carbon data. This could involve visual cues (e.g., green indicators for sustainable sites) or detailed reports.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some steps to diagnose and resolve typical problems:

• Invalid API Key (401 Unauthorized):
  • Check for typos: Ensure your API key is copied exactly as provided in your Website Carbon dashboard.
  • Key Activation: Verify that your API key is active. Sometimes, new keys might require a short activation period or email verification.
  • Correct Parameter Name: Confirm you are passing the key with the correct parameter name (api_key).
• Invalid URL Parameter (400 Bad Request):
  • URL Encoding: Ensure the target URL is properly URL-encoded, especially if it contains special characters. Although curl often handles this, it's a common issue with custom HTTP clients.
  • Complete URL: Provide a complete URL, including the https:// or http:// prefix.
  • Valid Domain: Confirm the domain is active and accessible.
• Rate Limit Exceeded (429 Too Many Requests):
  • Free Tier Limits: Remember the free tier has a limit of 100 requests per month. If you've exceeded this, you'll need to wait or upgrade your plan.
  • Rapid Retries: Avoid making too many requests in a short period. Implement delays between your requests if you're making multiple calls in quick succession.
• Server Errors (5xx):
  • Temporary Issue: A 5xx error (e.g., 500 Internal Server Error, 502 Bad Gateway) usually indicates a problem on the API provider's side. Wait a few minutes and try the request again.
  • Check Status Page: Refer to the Website Carbon homepage for any service announcements or a status page if available.
• No Response or Connection Timeout:
  • Network Connectivity: Check your own internet connection.
  • Firewall/Proxy: Ensure no local firewall or network proxy is blocking outgoing HTTP requests to api.websitecarbon.com.

Always consult the Website Carbon API documentation for the most up-to-date error codes and troubleshooting guidance.