Climatiq SDKs & Libraries: Official & Community Integrations

SDKs overview

Software Development Kits (SDKs) and libraries for Climatiq facilitate interaction with the Climatiq Carbon Emissions API, which provides access to a database of emissions factors and calculation capabilities. These tools abstract the underlying RESTful API, allowing developers to integrate carbon data and calculations into their applications using familiar programming language constructs. Climatiq offers official SDKs for popular languages, alongside opportunities for community-contributed libraries.

The primary function of these SDKs is to simplify common tasks such as authenticating API requests, querying emissions factors, and submitting data for carbon footprint calculations. By utilizing an SDK, developers can reduce the boilerplate code required for HTTP requests, JSON parsing, and error handling, focusing instead on the application's core logic. This approach aligns with best practices for API integration, promoting code reusability and maintainability.

For example, instead of manually constructing an HTTP POST request with an API key in the header and a JSON payload in the body for an emissions calculation, an SDK might provide a method like climatiq.estimate_emissions(activity_id, parameters). This method would handle the serialization of parameters, the secure transmission of the API key, and the deserialization of the API response into a native data structure, such as a Python dictionary or a JavaScript object.

Climatiq's API is designed as a RESTful service, which means it uses standard HTTP methods (GET, POST) and URIs for resource identification, typically returning data in JSON format. The official SDKs are built to leverage these REST principles while offering an idiomatic interface for each programming language. This design pattern is a common approach in modern web APIs, as detailed by the W3C's architectural styles for the web, ensuring broad compatibility and ease of use across different development environments.

Official SDKs by language

Climatiq provides official SDKs to streamline the integration of its Carbon Emissions API into various applications. These SDKs are maintained by Climatiq and are designed to provide a stable and consistent interface for developers.

The following table lists the currently available official SDKs:

Each official SDK is engineered to reflect the API's capabilities, including access to the emissions factors database and the core emissions calculation endpoints. They typically handle API key management, request serialization, response deserialization, and error handling, reducing the amount of custom code developers need to write for API interactions. Developers can find detailed usage examples and API specifics within the Climatiq developer documentation.

Installation

Installing Climatiq's official SDKs involves using the standard package managers for Python and Node.js. These installation methods ensure that the SDKs and their dependencies are correctly set up in your development environment.

Python SDK Installation

To install the Climatiq Python SDK, use pip, the Python package installer. It is recommended to install the SDK within a virtual environment to manage dependencies effectively and avoid conflicts with other Python projects.

# Create a virtual environment (optional, but recommended)
python3 -m venv climatiq_env
source climatiq_env/bin/activate # On Windows, use `climatiq_env\Scripts\activate`

# Install the Climatiq Python SDK
pip install climatiq

After installation, you can verify the successful setup by importing the climatiq library in a Python interpreter or script. More information is available in the Climatiq Python SDK installation guide.

Node.js SDK Installation

For the Node.js SDK, use npm (Node Package Manager) or yarn to add the package to your project. This will install the package and its dependencies into your node_modules directory and update your package.json file.

# Using npm
npm install @climatiq/climatiq

# Or using yarn
yarn add @climatiq/climatiq

Once installed, you can import the @climatiq/climatiq module into your Node.js or browser-based JavaScript applications. Detailed instructions and prerequisites are covered in the Climatiq Node.js SDK documentation.

Quickstart example

The following examples demonstrate how to make a basic emissions calculation using the official Python and Node.js SDKs, illustrating the process of authenticating and querying the Climatiq API.

Python Quickstart

This Python example shows how to estimate emissions for a given activity, such as electricity consumption, using the climatiq SDK. Replace YOUR_API_KEY with your actual Climatiq API key.

import climatiq
import os

# It's recommended to set your API key as an environment variable
# For demonstration, you can replace os.environ.get with your key directly
climatiq.api_key = os.environ.get("CLIMATIQ_API_KEY", "YOUR_API_KEY")

try:
    # Define the activity data for which to calculate emissions
    results = climatiq.estimate_emissions(
        {"energy": 100, "energy_unit": "kWh", "energy_type": "electricity", "country": "US"},
        emission_factor="electricity-grid_US"
    )

    print("Emissions Calculation Result:")
    print(f"Carbon Intensity: {results['carbon_intensity']} {results['carbon_intensity_unit']}")
    print(f"Emissions: {results['co2e']} {results['co2e_unit']}")
    print(f"Activities: {results['activities']}")

except climatiq.ClimatiqAPIException as e:
    print(f"An API error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

This script initializes the API client with your key, then calls the estimate_emissions method with the relevant parameters. The result includes the calculated CO2 equivalent emissions and other details. For more detailed examples and advanced usage, refer to the Climatiq Python SDK documentation examples.

Node.js Quickstart

This Node.js example demonstrates how to perform a similar emissions calculation using the @climatiq/climatiq SDK. Ensure you have your API key configured, ideally via an environment variable.

import { ClimatiqClient } from "@climatiq/climatiq";

// It's recommended to set your API key as an environment variable
// For demonstration, you can replace process.env.CLIMATIQ_API_KEY with your key directly
const client = new ClimatiqClient(process.env.CLIMATIQ_API_KEY || "YOUR_API_KEY");

async function getEmissionsData() {
  try {
    const results = await client.estimateEmissions({
      emissionFactor: "electricity-grid_US",
      parameters: {
        energy: 100,
        energy_unit: "kWh",
        energy_type: "electricity",
        country: "US",
      },
    });

    console.log("Emissions Calculation Result:");
    console.log(`Carbon Intensity: ${results.carbonIntensity} ${results.carbonIntensityUnit}`);
    console.log(`Emissions: ${results.co2e} ${results.co2eUnit}`);
    console.log(`Activities:`, results.activities);
  } catch (error) {
    console.error("An error occurred:", error.message);
  }
}

getEmissionsData();

This Node.js script instantiates the ClimatiqClient with the API key, then asynchronously calls the estimateEmissions method. The output provides the calculated carbon emissions data. Additional examples and API methods can be found in the Climatiq Node.js SDK guide.

Community libraries

Beyond the official SDKs, the Climatiq API's RESTful nature allows for the development of community-contributed libraries and integrations in various programming languages and environments. While Climatiq's official documentation primarily focuses on its first-party SDKs, the broader developer community often builds custom wrappers or integrations to suit specific project needs or preferred technology stacks.

Community libraries can offer several advantages, such as:

• Language support: Providing wrappers for languages not officially supported by Climatiq (e.g., Go, Ruby, Java, PHP).
• Framework integrations: Offering direct integrations with popular web frameworks (e.g., Django, Flask, Express.js, Ruby on Rails) to simplify data flow and authentication within those ecosystems.
• Specific use-case utilities: Developing tools tailored for particular applications, such as batch processing of emissions data or specialized reporting functions.
• Alternative paradigms: Implementing API interactions using different programming paradigms or stylistic preferences.

When considering a community library, developers should evaluate its documentation, active maintenance, community support, and alignment with the Climatiq API's specifications. As these libraries are not officially maintained by Climatiq, their stability, security, and feature completeness may vary. Developers are encouraged to review the source code and community feedback before incorporating them into production systems.

As of late 2024, the primary recommended approach for integrating with Climatiq remains through the official SDKs due to their direct support and maintenance. However, the open nature of REST APIs means that developers are not restricted to these tools and can build their own clients or contribute to open-source efforts. Platforms like GitHub are common repositories for such community-driven projects, where developers can find and contribute to various API client libraries.