Batch Endpoints

Many of the endpoints in the Climatiq API have batch variants for handling multiple operations in a single request. These endpoints are particularly useful when you have a substantial amount of data to process and are seeking optimal performance. By using batch endpoints, you not only reduce the overhead associated with multiple HTTP connections but also benefit from the batch-specific optimizations that Climatiq implements.

Endpoints that have a batch variant will have this documented next to the endpoint in the API reference documentation for that endpoint, such as basic estimate or procurement.

When working with batch endpoints, you'll find that they uniformly accept arrays, and return an object with a results array inside it. Each element in the request array should be a standalone body that would typically be sent to the regular endpoint. Correspondingly, the results array contains individual results for each of these elements.

Batch endpoints always preserves the order between requests and responses. This means that the first request object always corresponds to the first response object, the second request object to the second response object and so on.

Currently, all batch endpoints are limited to a maximum of 100 operations per request. If you supply more than 100 elements, an error is returned.

Handling Errors

Individual operations within batch endpoints can fail for a variety of reasons. However, the batch endpoints returns a status code of 200, even if some or all of the operations within it fail. To determine what operations have failed, you should inspect the result of each operation. For more details on errors in the Climatiq API, see the errors documentation

While for the most part operations fail independently, the entire batch endpoint call might fall. This can happen e.g. if the JSON body is not parseable, or your authorization is invalid.

Example

An example is the batch variant of the basic estimate endpoint. Where the regular estimate endpoint might take in the following body:

{
    "emission_factor": {
        "activity_id": "electricity-supply_grid-source_residual_mix",
        "data_version": "^6"
    },
    "parameters": {
        "energy": 100,
        "energy_unit": "kWh"
    }
}

The batch endpoint takes in an array of objects, each which should be a valid body to the non-batch variant. In the example below, we'll call the batch variant with one array element that will lead to a successful operation, and one which won't.

[
    {
        "emission_factor": {
            "activity_id": "electricity-supply_grid-source_residual_mix",
            "data_version": "^6"
        },
        "parameters": {
            "energy": 100,
            "energy_unit": "kWh"
        }
    },
    {
        "emission_factor": {
            "activity_id": "electricity-supply_grid-source_residual_mix"
        },
        "parameters": {
            "energy": 100,
            "energy_unit": "kWh"
        }
    }
]

And the response body would be as follows, where you can see the second operation has failed because no data_version was provided:

{
    "results": [
        {
            "co2e": 95.42,
            "co2e_unit": "kg",
            "co2e_calculation_method": "ar4",
            "co2e_calculation_origin": "source",
            "emission_factor": {
                "name": "Electricity supplied from grid - residual mix",
                "activity_id": "electricity-supply_grid-source_residual_mix",
                "id": "eefd06c3-1c7a-447c-aaf5-fe958bfa470e",
                "access_type": "public",
                "source": "AIB",
                "source_dataset": "European Residual Mix",
                "year": 2022,
                "region": "RS",
                "category": "Electricity",
                "source_lca_activity": "electricity_generation",
                "data_quality_flags": ["partial_factor", "notable_methodological_variance"]
            },
            "constituent_gases": {
                "co2e_total": 95.42,
                "co2e_other": null,
                "co2": 95.42,
                "ch4": null,
                "n2o": null
            },
            "activity_data": {
                "activity_value": 100.0,
                "activity_unit": "kWh"
            },
            "audit_trail": "selector"
        },
        {
            "error": "bad_request",
            "error_code": "invalid_input",
            "message": "Selector should either provide an 'id', OR a 'data_version' and an 'activity_id'. It must not provide both. The latest 'data_version' is '6.6'"
        }
    ]
}