Regions

The geographical location of an emission-generating activity or the location of financial expenditure is important when it comes to carbon emissions estimations.

Different farming and production practices, electricity grid makeups, and other regional factors can make a big difference in how much the same activity emits. Every Climatiq emission factor specifies a region it is valid for.

Climatiq uses two different types of geographical data:

Region Codes: Text-based identifiers that define the geographic scope where an emission factor applies (e.g., DK for Denmark, US-CA for California).
Locations: Precise location data, primarily used for distance and routing calculations

Region Code

A region code in Climatiq is a way to represent a geographical area. This identifier shows up in emission factors and can be used as input for various endpoints. Region codes come in two different formats:

Country-Level Region Code

The most common format for region codes is the country-level region code. It is a two-letter country code, like DK for Denmark or GB for Great Britain. Apart from the special cases (see below), these codes follow the ISO 3166-1 alpha-2 standard .

The majority of emission factors are applicable at the country level. This means that when you are using a region code for input, the country-level region codes is often detailed enough. Using an extended region code will often not lead to more accurate estimations.

Extended Region Code

When you need more precision, Climatiq supports specifying an extended region code, consisting of two parts. The first part is a country-level region code, and the second is an extension. The two parts are separated by a hyphen(-).

Extensions can be:

ISO-3166-2 subdivision codes: Representing states, provinces, or similar administrative regions.
A UN/LOCODE representing locations such as cities, airports, railway stations and similar.

Examples:

US-CA for California, United States
US-NY for New York State, United States
US-NYC for New York City, United States
GB-LND for London, United Kingdom

For the most part, you will only see extended region codes when dealing with:

Large countries where emissions vary significantly from state to state, such as the United States.
Specifying UN/LOCODEs for a specific location in travel or freight-related endpoints.

Special Cases

Sometimes emissions data applies in ways that are not covered by the above standards. In cases like that you might see region strings that have values in them that do not follow the standards.

Some examples of these region codes are:

EU for emission factors applicable within the European Union
GLOBAL for emission factors that are applicable globally
US-AKGD is the region covering the ASCC Alaska power Grid
ROW_WF is for emission factors that cover “Africa except Egypt and South Africa”

Some of these special cases might have underscore in the names. Underscores do not necessarily mean it is a extended region code, as only hyphens denote that.

Location

For scenarios that require precise locations (such as shipping or travel), Climatiq supports specifying locations. These can be specified in two formats.

Location Objects: Specifying the location as an object allows you to specify exactly the kind of data you have, whether it is an IATA code, a UN/LOCODE, coordinates, or just a free-text description of the location.
Location Strings: Location strings are a convenient way to let Climatiq automatically detect the kind of location data you have. Simply provide a string and Climatiq will automatically detect what format it is. However there are some advanced parameters that location strings do not give access to, such as explicitly specifying country or postal codes.

If you have additional parameters or want to be explicit about the location type, you should use a location object, otherwise use a location string.

Location String

A location string is the most convenient way to specify a location. You provide a string value directly, and Climatiq will automatically detect what location object it should be parsed as. This is particularly useful for unstructured data.

While location strings are convenient, they do not give full access to all parameters, such as specifying country or postal codes explicitly. If you have this data in a structured way, we recommend you use location objects directly.

Examples

The following location string will be parsed as an IATA Code Location


{ "location": "JFK" }

The following location string will be parsed as a pair of latitude/longitude coordinates in a Coordinate Location.


{ "location": "53.570470,10.024413" }

The following location string will be parsed as a UN/LOCODE Location


{ "location": "DE-BER" }

Any strings that do not match the formats above, will be parsed as a Query Location


{ "location": "10 Downing Street" }

Query Location

A Query Location allows Climatiq to search for a match based on unstructured free-text input, such as addresses or city names.

Coverage limitations

Not all regions are covered equally well. See the section on restricted geo data for more information.

Query Location Attributes	Required
query string A free text description of the location, like `"Berlin, Germany"`, or `"10 Downing Street"`.	optional
country string The 2-letter ISO-3166 country code for a given location. If you know the country, we recommend you provide it here.	optional
postal_code string The postal (or zip) code for the location. If used, `country` must also be specified.	optional

At least one of the following is required:

query alone
country + postal_code

If this returns an incorrect location, consider supplying the country parameter, as this will ensure the location is within the provided country.

Not all countries have support for postal codes, and the format might be different from country to country. See this table for details on postal codes.


{ "location": { "query": "Hamburg" } }


{ "location": { "country": "DE", "postal_code": "10178" } }

IATA Code Location

An IATA Code Location allows you to specify locations using IATA airport codes.

IataLocation Attributes	Required
iata string An IATA airport code.	required


{ "location": { "iata": "LHR" } }

UN/LOCODE Location

A UN/LOCODE Location allows you to use an extended region code to find a location.

UN/LOCODE Location Attributes	Required
locode string An extended region code like `DE-BER` for Berlin. It must be an extended region code with the second part being a UN/LOCODE.	required


{ "location": { "locode": "US-SFO" } }

Coordinate Location

A Coordinate Location lets you use latitude and longitude to define a location, and you can optionally include a country code.

Coordinate Location Attributes	Required
longitude float The longitude of the coordinate.	required
latitude float The latitude of the coordinate.	required
country string Climatiq automatically determines the country the coordinates are within. If the automatically determined country is wrong, you can override this selection by supplying a 2-letter country code.	optional


{
    "location": {
        "latitude": 52.52,
        "longitude": 13.4
    }
}

Restricted Geo data

Some countries are restrictive about the distribution and use of their geographical information. Finding and routing between locations in such countries may not always be possible.

Known countries with this kind of restriction are the People’s Republic of China, the Republic of Korea, and the Democratic People’s Republic of Korea.