Carbon Interface Getting Started: A Developer's Guide (2026)

Getting started overview

Integrating with Carbon Interface involves a sequence of steps designed to get developers making their first carbon emissions calculation requests quickly. The process typically includes creating an account on the Carbon Interface website, generating an API key for authentication, and then constructing an API request using a tool like cURL or a preferred programming language. The Carbon Interface API is documented as RESTful, accepting JSON payloads and returning JSON responses.

Before making live requests, developers often interact with a testing environment. Carbon Interface provides a free Developer tier that allows up to 50 API requests per month, which is suitable for initial setup and testing. This process follows standard API consumption patterns, where an API key acts as a credential to authorize access to protected resources, as described in general Google Cloud API key documentation.

The following table provides a quick reference for the initial setup:

Create an account and get keys

To access the Carbon Interface API, a developer must first register for an account. This process typically involves providing an email address and creating a password. Upon successful registration, users are directed to their account dashboard.

1. Sign up for an account: Navigate to the Carbon Interface signup page. Complete the registration form with your details.
2. Access the dashboard: After signing up, you will typically be logged in automatically and redirected to your Carbon Interface dashboard.
3. Locate API Keys: Within the dashboard, there is a dedicated section for managing API keys. The exact location may vary but is commonly labeled as 'API Keys', 'Developer Settings', or similar.
4. Generate/Copy API Key: Carbon Interface usually provides a default API key upon account creation. If not, there will be an option to generate a new key. Copy this key immediately, as it is essential for authenticating all your API requests. It is good practice to treat API keys as sensitive credentials, similar to how AWS recommends managing access keys, and avoid hardcoding them directly into public repositories.
5. Understand key types (if applicable): Some APIs offer different types of keys (e.g., public vs. secret, test vs. live). Review the Carbon Interface documentation to understand if there are distinctions and which key to use for development versus production environments. Carbon Interface's free tier is designed for development and testing.

The API key functions as a unique identifier and authentication token. When making requests to Carbon Interface, this key must be included in the request headers to verify your identity and authorize access to the service. Failure to include a valid API key will result in authentication errors.

Your first request

Once you have an API key, you can make your first authenticated request to Carbon Interface. This example demonstrates how to calculate the carbon emissions for a flight. The Carbon Interface API is RESTful, so requests are made to specific endpoints using standard HTTP methods like POST.

Example: Calculating flight emissions

This example uses the /estimates endpoint to calculate emissions for a flight. You will need your API key, which should be included in the Authorization header.

Request structure (cURL)

Replace YOUR_API_KEY with the actual API key copied from your dashboard. This cURL command sends a POST request to the flights estimate endpoint with the necessary JSON payload.

curl -X POST \
  https://www.carboninterface.com/api/v1/estimates \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "flight", "passengers": 1, "legs": [ { "departure_airport": "sfo", "destination_airport": "nyc" } ] }'

Request parameters explained:

• -X POST: Specifies the HTTP POST method.
• https://www.carboninterface.com/api/v1/estimates: The API endpoint for creating estimates.
• -H 'Authorization: Bearer YOUR_API_KEY': Sets the Authorization header with your API key. The Bearer scheme is a common pattern for OAuth 2.0 bearer tokens, though here it's used with an API key.
• -H 'Content-Type: application/json': Indicates that the body of the request is in JSON format.
• -d '{ "type": "flight", "passengers": 1, "legs": [ { "departure_airport": "sfo", "destination_airport": "nyc" } ] }': The JSON request body containing the details for the flight estimate.
• type: Specifies the type of estimate, in this case, "flight".
• passengers: The number of passengers for the flight (e.g., 1).
• legs: An array defining the flight segments. Each leg includes departure_airport and destination_airport (using IATA codes).

Expected JSON response:

A successful request will return a JSON object containing the estimated carbon emissions and other relevant data. The structure will generally resemble:

{
  "data": {
    "id": "some-unique-id",
    "type": "estimate",
    "attributes": {
      "footprint_kg": 123.45,
      "footprint_mt": 0.12345,
      "estimated_at": "2023-10-27T10:00:00.000Z",
      "carbon_g": 123450,
      "carbon_lb": 272.16,
      "carbon_kg": 123.45,
      "carbon_mt": 0.12345,
      "distance_unit": "km",
      "distance_value": 3924.9
    }
  }
}

The footprint_kg (kilograms) or carbon_g (grams), carbon_lb (pounds), carbon_kg (kilograms), carbon_mt (metric tons) fields will contain the calculated carbon emissions. Other fields provide metadata about the estimate.

Common next steps

After successfully making your first request, several common next steps can help you further integrate and utilize Carbon Interface:

1. Explore other endpoints: Carbon Interface offers various endpoints for different types of emissions calculations, including shipping, electricity, and vehicle estimates. Review the API reference to identify other functionalities relevant to your application.
2. Integrate into your application: Move beyond cURL and integrate the API calls into your preferred programming language. Carbon Interface provides code examples in Python, Ruby, Node.js, Go, and PHP.
3. Error handling: Implement robust error handling in your code to gracefully manage API errors, such as invalid requests, authentication failures, or rate limit exceeded responses. Understanding standard HTTP status codes is crucial for this.
4. Monitor usage: Keep track of your API usage through your Carbon Interface dashboard to ensure you stay within your plan's limits, especially if using the free Developer tier.
5. Upgrade your plan: If your application requires more than 50 requests per month or needs additional features, consider upgrading to a paid plan, which starts at $99/month for 5,000 requests.
6. Security best practices: Ensure your API key is stored securely and not exposed in client-side code or public repositories. Use environment variables or a secure secret management system.
7. Asynchronous processing: For applications making numerous requests, consider implementing asynchronous API calls to improve performance and user experience.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

• Check your API Key: Ensure the API key in your Authorization: Bearer YOUR_API_KEY header is correct and hasn't expired. Double-check for typos or extra spaces.
• Verify Endpoint URL: Confirm that the API endpoint URL is accurate (e.g., https://www.carboninterface.com/api/v1/estimates). Refer to the Carbon Interface API reference for the correct paths.
• Content-Type Header: The API expects a Content-Type: application/json header for POST requests with a JSON body. Ensure this header is present and correctly formatted.
• JSON Payload Format: Validate that your JSON request body is well-formed and adheres to the structure expected by the API. Missing commas, unquoted keys, or incorrect data types can cause parsing errors. Online JSON validators can be helpful.
• HTTP Method: Confirm you are using the correct HTTP method (e.g., POST for creating estimates).
• Rate Limiting: If you receive a 429 Too Many Requests error, you might have exceeded the request limit for your current plan. Check your dashboard for usage statistics. The Developer tier has a limit of 50 requests per month.
• Error Messages: Pay close attention to the error messages returned in the API response. They often provide specific details about what went wrong (e.g., 401 Unauthorized for invalid API key, 400 Bad Request for malformed payload).
• Network Connectivity: Ensure your development environment has an active internet connection and is not blocked by a firewall from accessing carboninterface.com.
• Consult Documentation: The official Carbon Interface documentation provides detailed error codes and explanations that can help diagnose specific issues.
• Contact Support: If you've exhausted all troubleshooting steps, consider reaching out to Carbon Interface support for assistance.