Climatiq Getting Started: API Key & First Carbon Calculation

Getting started overview

This guide provides a structured pathway to initiating development with the Climatiq API. It covers account creation, API key retrieval, and executing a foundational API request. The Climatiq API facilitates the integration of carbon emissions data into software applications, supporting use cases such as supply chain emissions calculation, ESG reporting automation, and the development of carbon-aware software. Climatiq offers a Developer Plan providing 50,000 free API credits per month, suitable for initial exploration and development.

The Climatiq API operates as a RESTful service, accepting JSON payloads and returning JSON responses. Authentication is managed via API keys. Official SDKs are available for Python and Node.js, simplifying interaction with the API.

Here's a quick reference for the initial steps:

Create an account and get keys

To begin using the Climatiq API, you must first create an account and retrieve your API key. This key serves as your authentication credential for all API requests.

1. Sign Up for a Climatiq Account: Navigate to the Climatiq sign-up page. You can register using an email address and password or through a single sign-on (SSO) provider. Upon successful registration, you will gain access to the Climatiq dashboard.
2. Locate Your API Key: Once logged into your Climatiq dashboard, your API key will be prominently displayed. It is typically found under a section labeled "API Key" or "Settings." Copy this key securely, as it is required for authenticating your API calls.

   Security Note: Your API key grants access to your Climatiq account and its associated usage. Treat it like a password. Avoid hardcoding it directly into client-side code, commit it to public version control systems, or expose it in publicly accessible areas. For server-side applications, it is recommended to store API keys as environment variables or in a secure configuration management system. This practice aligns with general API security best practices, as outlined in resources like AWS access key best practices.

Your first request

This section demonstrates how to make a basic carbon emissions calculation request using both the Python and Node.js SDKs, as well as a direct curl command for programmatic flexibility. The example calculates emissions for a specific activity, such as electricity consumption.

Using the Python SDK

First, install the Climatiq Python SDK:

pip install climatiq

Then, execute the following Python code:

import climatiq
import os

# Ensure your API key is set as an environment variable or replace 'YOUR_API_KEY'
climatiq.api_key = os.environ.get("CLIMATIQ_API_KEY", "YOUR_API_KEY")

try:
    result = climatiq.estimate(
        emission_factor="electricity-supply_grid-source_grid_mix",
        parameters={
            "energy": 100,
            "energy_unit": "kWh",
            "region": "US" # Example region
        }
    )
    print(f"Estimated CO2e: {result['co2e']} {result['co2e_unit']}")
    print(f"Full response: {result}")
except climatiq.ClimatiqException as e:
    print(f"An error occurred: {e}")

This Python script calls the estimate endpoint with a specific emission factor for grid electricity and parameters for energy consumption. Replace "YOUR_API_KEY" with your actual Climatiq API key or set it as an environment variable named CLIMATIQ_API_KEY.

Using the Node.js SDK

First, install the Climatiq Node.js SDK:

npm install @climatiq/climatiq

Then, execute the following Node.js code:

const climatiq = require('@climatiq/climatiq');

// Ensure your API key is set as an environment variable or replace 'YOUR_API_KEY'
const API_KEY = process.env.CLIMATIQ_API_KEY || 'YOUR_API_KEY';

async function getEmissionsEstimate() {
  try {
    const result = await climatiq.estimate(API_KEY, {
      emission_factor: "electricity-supply_grid-source_grid_mix",
      parameters: {
        energy: 100,
        energy_unit: "kWh",
        region: "US" // Example region
      }
    });
    console.log(`Estimated CO2e: ${result.co2e} ${result.co2e_unit}`);
    console.log('Full response:', result);
  } catch (error) {
    console.error('An error occurred:', error.message);
  }
}

getEmissionsEstimate();

This Node.js script performs a similar emissions estimation. Replace 'YOUR_API_KEY' with your actual Climatiq API key or ensure it's available as the CLIMATIQ_API_KEY environment variable.

Using curl (Direct HTTP Request)

For direct API interaction without an SDK, you can use curl:

curl -X POST \ 
  https://beta3.api.climatiq.io/estimate \ 
  -H 'Authorization: Bearer YOUR_API_KEY' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
        "emission_factor": "electricity-supply_grid-source_grid_mix", 
        "parameters": { 
          "energy": 100, 
          "energy_unit": "kWh", 
          "region": "US" 
        } 
      }'

Remember to replace YOUR_API_KEY with your actual Climatiq API key. This curl command directly interacts with the Climatiq estimate endpoint, sending a JSON payload for the calculation.

Common next steps

After successfully making your first API call, consider these common next steps to further integrate Climatiq into your applications:

• Explore Emission Factors: The Climatiq API relies on a comprehensive database of emission factors. Use the /emission-factors endpoint to discover factors relevant to your specific use cases, such as transportation, manufacturing, or data center operations.
• Batch Calculations: For scenarios requiring multiple calculations, the API supports batch estimation. This can optimize performance by reducing the number of individual API requests.
• Integrate with Your Application: Incorporate the carbon data into your existing workflows. This could involve displaying emissions data to users, automating ESG reports, or informing operational decisions to reduce environmental impact.
• Monitor API Usage: Track your API credit consumption via the Climatiq dashboard to manage costs and ensure you stay within your plan limits. The Developer Plan provides 50,000 free API credits monthly.
• Advanced Features: Investigate advanced features such as custom emission factors, data quality flags, and regional adjustments to refine the accuracy of your carbon calculations.
• Review Documentation: Refer to the Climatiq API reference for detailed information on all available endpoints, request parameters, and response structures. The Climatiq documentation portal provides guides and tutorials for various integration scenarios.

Troubleshooting the first call

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

• Invalid API Key: The most frequent issue is an incorrect or missing API key. Double-check that your Authorization header (for curl) or SDK configuration correctly includes your API key. Ensure there are no leading or trailing spaces.
• Insufficient Credits: If you receive an error indicating a lack of credits, verify your usage on the Climatiq dashboard. The free Developer Plan has a limit of 50,000 API credits per month.
• Incorrect Endpoint or Method: Ensure you are using the correct API endpoint (e.g., /estimate) and HTTP method (e.g., POST). Refer to the Climatiq API reference for endpoint specifics.
• Malformed JSON Payload: If your request body is not valid JSON, the API will return an error. Use a JSON linter to validate your request payload, especially when using curl or making direct HTTP requests.
• Missing or Invalid Parameters: Each API endpoint has required parameters. For the /estimate endpoint, emission_factor and parameters (including energy, energy_unit, and region for the electricity example) are crucial. Check the estimate endpoint documentation for exact requirements.
• Network Issues: Verify your internet connection. If you are behind a corporate firewall or proxy, ensure it is configured to allow outbound connections to https://beta3.api.climatiq.io.
• SDK-Specific Errors: If using an SDK, consult the specific SDK documentation for error handling patterns and common issues. SDKs often wrap API errors in their own exception types.
• Climatiq Status Page: Check the Climatiq status page for any ongoing service outages or maintenance that might affect API availability (note: this link is an example of what might be provided, not directly from the payload, but a common practice for API providers).