Skip to Content
API ReferenceModelsSelector

Selector

A Selector is the model you use if you’re selecting an emission factor yourself. A Selector allows you to select a specific emission factor via two distinct methods:

  1. You can use an activity ID for the particular activity you are interested in. As activity IDs can refer to multiple emission factors, you use the other metadata fields that Climatiq provides to filter down to those most suitable for your use case.
  2. You can use a unique ID which will always refer to the same emission factor

Using Activity ID

Emission factors can be queried by specifying a data version, an activity ID and a set of optional attributes. If more than one emission factor match the filtering criteria, the one from most recent year will be selected, followed by the most conservative (e.g. highest) if there is more than one available for the most recent year.

Selector Attributes
  • data_versionrequired string

    The required Data Version string for this request.

  • activity_idrequired string

    An ID describing the activity that to search for. Multiple emission factors can share the same activity_id, e.g. if they are from a different source or apply to a different region.

  • sourcestring

    Emission factor data source name.

  • source_datasetstring

    The name of the dataset the source published this emission factor under.

  • regionstring

    A region code describing the geographic region to which the emission factor applies.

  • region_fallbackboolean
    Default value: false

    Set this to true if you're willing to accept a less specific geographical region than the one you've specified. Climatiq will then attempt to fall back to the larger region if it does not find any emission factors with the initial region. Only one fallback can be specified at a time. Default is false

  • year_fallbackboolean
    Default value: false

    Set this to true if you're willing to accept a less specific year than the one you've specified. Climatiq will then attempt to find an emission factor with a year as close as possible to the one you've provided. Only one fallback can be specified at a time. Default is false

  • yearinteger

    The year in which the emission factor is considered most relevant, according to the source.

  • scopestring

    The scope which the emission factor might apply to. Can be values like "1", "2", "3" or "3.1".

  • source_lca_activitystring

    The Life Cycle Assessment (LCA) activity to which this factor is associated.

  • calculation_method"ar4", "ar5" or "ar6"

    The calculation method that will be used to calculate the CO2e emission factor. Learn more about calculation methods here.

  • allowed_data_quality_flagsarray of strings

    A list of data quality flags that you are willing to allow for this estimate. See the guide on data quality flags for more information and defaults. You can supply an empty list [] if you only want to accept emission factors without detected data quality issues.

A selector for a specific activity, with additional filtering criteria can look like this:

"emission_factor": {
    "data_version": "^3",
    "activity_id": "electricity-supply_grid-source_production_mix",
    "source": "MfE",
    "region": "NZ",
    "year": 2020
}

Using ID

Every emission factor has a unique ID, and if we update an emission factor in a new data version, it gets a new ID, so by using an ID as your selector, you can assure that you get consistent results. This could be useful for audit purposes.

Selector Attributes
  • idrequired string

    An unique ID for one particular emission factor

  • calculation_method"ar4", "ar5" or "ar6"

    The calculation method that will be used to calculate the CO2e emission factor. Learn more about calculation methods here.

A selector for one specific emission factor, using the unique id for that emission factor can look like this:

"emission_factor": {
    "id": "da80d5f9-7fb2-4cd7-aa45-781479499845",
}

FAQ

What happens if an activity_id is not found in the specified region?

If an activity_id is not found in the specified region, the behavior depends on the region_fallback parameter:

  • If region_fallback is false (default): The API will return an error indicating that no emission factor was found for the specified criteria.
  • If region_fallback is true: The API will automatically fall back to a larger, less specific geographical region to find a matching emission factor. For example, if you specify a specific country and no factor is found, it might fall back to a continental or global region. If no emission factor can still not be found, the API will return an error.
Last updated on
ModelsParameters