BeZero logo
API docs by Redocly

BeZero Ratings API (3.0.0)

Download OpenAPI specification:Download

BeZero Engineering: engineering@bezerocarbon.com

BeZero Ratings API Migration Guide v2 to v3

Introduction to the Ratings API

The BeZero Ratings API provides information about project ratings in a standard JSON response. The API is authenticated using OAuth 2.0.

With our API integration technology, participants can display the BeZero Carbon Rating and rating summary on their platform. Whether an exchange, a data provider, a marketplace or a broker, with our API solution you can provide end users with BeZero Carbon ratings.

BeZero Rating Scale

The BeZero Carbon Rating represents BeZero’s opinion on the likelihood that a given credit achieves a tonne of CO₂e avoided or removed from the atmosphere. With ‘AAA’ representing the highest likelihood, and ‘D’ representing the lowest, the rating scale is fully aligned with financial market standards, making it easy to interpret. On the API, the rating will be returned on an 8-point scale from AAA to D.

BeZero Watch Status

BeZero Carbon ratings can be put ‘On Watch’ if new information comes to light. A process of review begins and at the end of this process different outcomes are possible:

  • upgrade the rating to a level higher than at present
  • downgrade the rating to a level lower than at present or
  • reaffirm the rating at current levels.

Simultaneously, the rating will be ‘removed from watch’. On the API, the watch status will be returned as a boolean True/False. The watch status needs to be shown next to the rating if that project is on watch and until that watch status is removed. The API will provide the updated rating along with the watch status.

BeZero Withdrawn Ratings

BeZero Carbon Ratings are assigned only to projects meeting a predefined eligibility criteria. These include documented tests on additionality, formal audit processes and continued public availability of all relevant information. BeZero Carbon Ratings may be withdrawn in case there is a material impairment in the project’s ability to meet any of the eligibility criteria including partial or complete withdrawal or unavailability of relevant information in public domain. BeZero may also withdraw its ratings in case BeZero Carbon becomes aware of any risks with respect to the ownership of the project and/or usage rights. All rating withdrawals are published on the BeZero API. For ratings that have been withdrawn, the API will return a Withdrawn status.

BeZero Rating Vintage Range

The BeZero rating applies to credits within the vintage range returned by the API as the Vintage Start and End date.

For more insight into the BeZero Carbon Rating methodology please refer to https://bezerocarbon.com/ratings/resources

Authentication and credential provision

A token can be acquired using the standard OAuth 2.0 authorisation flow from the BeZero Token Server using the access keys we provide. BeZero will provide a Production set of Client ID and Client Secrets that will allow you to authenticate with the Ratings API.

OAuth2

This API uses OAuth 2 with Client Credentials

Security Scheme Type: OAuth2
Flow type: clientCredentials
Token URL: https://login.bezerocarbonmarkets.com/oauth2/token
Scopes:
  • bcm/v3.ratings:list -

    list ratings

  • bcm/v3.ratings:details -

    read rating details

  • bcm/v3.ratings:riskFactors -

    read rating risk factors

  • bcm/v3.projects:list -

    list projects

Rate limiting

The API is rate limited to 1000 requests per minute, any more requests than this will result in a 429 Too Many Requests, it allows retry after 1 minute.

API version selection

Clients can opt into changes by attaching a Accept-API-Version header. If the header is omitted, the API defaults to 3.0 behaviour. Currently supported values are 3.0 and 3.1. Requests with an unsupported Accept-API-Version value will be rejected with 400 Bad Request. Responses include the resolved Accept-API-Version header so clients can confirm which compatibility version was applied. 3.0 will exclude all but the first published rating for a project. 3.1 will return multiple ratings for a single project, if any have been published.

List Ratings

The ratings endpoint returns a list of BeZero ratings. Each page returns 100 ratings before it is paginated and the list is filterable by the dataLastUpdatedAt timestamp. Change to any of the data returned by ratings list or ratings details will update the dataLastUpdatedAt timestamp. You can filter the list using changedSince to only return any changes that may have occurred since the last query, to minimise API calls. queryLatestChanges is provided at the end of each paginated page to provide a timestamp of when the API was last called. BeZero ratings can change or be put on watch at any time and so polling for updates at least once per day is recommended.

Authorizations:
OAuth2
query Parameters
changedSince
string
Example: changedSince=2024-07-10T09:46:11Z

optional ISO 8601 datetime string, when provided will filter out ratings where the data has not changed since provided date

page
integer
Example: page=1

optional pagination value

header Parameters
Accept-API-Version
string
Enum: "3.0" "3.1"

Optional compatibility version. If omitted, the API defaults to 3.0 behavior.

Responses

Request samples 

TOKEN="$(curl https://login.bezerocarbonmarkets.com/oauth2/token -d "grant_type=client_credentials" \
    -d "client_id=<CLIENT_ID>" \
    -d "client_secret=<CLIENT_SECRET>" \
    -d "scope=bcm/v3.ratings:list" | jq -r .access_token)"

curl -H"Authorization: Bearer $TOKEN" -H"Accept-API-Version: 3.1" https://api.bezerocarbonmarkets.com/v3/ratings

Response samples

Content type
application/json
{
  • "ratings": [
    ],
  • "links": {
    }
}

Get Rating Details

The rating details endpoint returns additional information about a BeZero rating. For users interested in the textual summary analysis for a specific BeZero rating, this can be found by following the link in the ratings list response or by providing the project ID in the GET request. Summary analysis and ratings are updated together so users are recommended to get the rating and rating detail when requesting updates, otherwise the rating and rating summary will be out of sync.

Authorizations:
OAuth2
path Parameters
ratingID
required
string

The BeZero Carbon unique identifier for this rating

header Parameters
Accept-API-Version
string
Enum: "3.0" "3.1"

Optional compatibility version. If omitted, the API defaults to 3.0 behavior.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "summaryAnalysis": "string"
}

Premium: Risk factors

The risk factors endpoint is a Premium endpoint that returns a risk factor score for each BeZero rated project. The risk factors can have a score of aaa, aa, a, bbb, bb, b, c, d. Ratings, risk factors and summary analysis are always updated together so users are recommended to get the rating, rating detail and risk factors when requesting updates. Otherwise rating, rating summary and risk factor scores will be out of sync.

Authorizations:
OAuth2
path Parameters
ratingID
required
string

The BeZero Carbon unique identifier for this rating

header Parameters
Accept-API-Version
string
Enum: "3.0" "3.1"

Optional compatibility version. If omitted, the API defaults to 3.0 behavior.

Responses

Response samples

Content type
application/json
{
  • "id": "ABC123",
  • "additionality": {
    },
  • "carbonAccounting": {
    },
  • "permanence": {
    }
}

List Projects

This endpoint returns projects for which BeZero has a rating. It is sorted by dataLastUpdatedAt and paginated into 100 projects. BeZero can add new ratings at any time so BeZero recommends calling this endpoint at the same cadence as the ratings list, using the changedSince functionality to filter for any changes.

Authorizations:
OAuth2
query Parameters
changedSince
string
Example: changedSince=2024-07-10T09:46:11Z

optional ISO 8601 datetime string, when provided will filter out ratings where the data has not changed since provided date

page
integer
Example: page=1

optional pagination value

header Parameters
Accept-API-Version
string
Enum: "3.0" "3.1"

Optional compatibility version. If omitted, the API defaults to 3.0 behavior.

Responses

Response samples

Content type
application/json
{
  • "projects": [
    ],
  • "links": {
    }
}