Greenly Carbon Analytics API (1.5)

Download OpenAPI specification:Download

Introduction

The Greenly Carbon Analytics API is a set of RESTful services which enable the enrichment of bank transactions with carbon footprint analytics.

All request and response payloads, including errors, use the JSON naming convention.

2 API environments are available: a sandbox environment used to test the API capacities and your integration with these services and the production environment.

To have access to these environments, you will need to obtain API keys by contacting us at contact@greenly.earth.

The 2 environments are available at the following URL:

Getting Started

You can download our sample Postman requests at the following URL: http://offspend.github.io/PostmanRequests.zip

You then need to add your API key in the Greenly Sandbox API environment. After that, you should be able to create a user. Executing this Postman request will automatically set the latest created userId as a global env in your Postman environment. So after creating this user, you can directly try all the other requests including the Calculate Carbon Footprints one which will show you the carbon footprint analysis for a lot of different transactions.

Input Transaction Labels

The algorithm classifies transactions to providers and purchase categories so as to measure their carbon footprint based on their labels. In the best case, this label would consist only of the name of the recipient of the payment. Yet, in general, raw label contain overhead information, related in particular to the type of payment and the date of the transaction.

In the case where a cleaning of the overhead is done on the bank side, only the cleaned label should be transmitted to the API. If no cleaning is done or the cleaning is deemed to be too noisy or unreliable, raw labels can be also transmitted to the API.

Indeed, when a label is received, the classification algorithm looks for all common overhead patterns, such as “CB XXXXX”, “paiement par carte”, or “01/06/2020”, among many other overhead patterns.The classification algorithm removes all such patterns used by all banks that it was possible to enumerate during the R&D process. Yet, it is always possible that some patterns could not be found, or that the format evolves at some time. In that case, the cleaning of the pattern should either be done at the user side, or the user should contact the Greenly support team to ensure proper cleaning of the raw label and hence proper classification and estimation of the carbon footprint.

As a toy example, let us consider the following raw label to illustrate the allowed format: “paiement par carte super u 35 st jacques de 05/07”. Providing the “cleaned label” would be “super u 35 st jacques de“ or variations thereof, and as it can be observed the cleaned label does not need to be perfectly informative nor cleaned. As mentioned above, it is also possible to simply provide the raw label and the API will take care of removing the date and the overhead linked to card payment. Yet, it is not desired to provide both cleaned and raw labels using a separator (e.g. a new line ‘ ’ separator or other variations) as this would lead to degraded performances.

Authentication

api_key

Security Scheme Type API Key
Header parameter name: api-key

purchaseCategories

Try it

Get all purchase categories

Retrieve the details of all purchase categories.

Responses

Response samples

Content type
application/json
[
  • {
    }
]
Try it

Get purchase category

Retrieve the details of one purchase category.

path Parameters
purchaseCategoryId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "methodology":
    {
    },
  • "parentPurchaseCategory": "Transport",
  • "translations":
    {
    },
  • "possibleTags":
    [
    ],
  • "id": "string"
}

users

Try it

Create user

Create a user.

Responses

Response samples

Content type
application/json
{
  • "defaultTagValues":
    [
    ],
  • "userId": "string"
}
Try it

Update user

Update a user with new default tag values. All previous tag values are replaced (the two objects are not merged) so you must provide all tag values that apply to the user during each call.

path Parameters
userId
required
string
Request Body schema: application/json
required
Array of objects (TagValue)

Responses

Request samples

Content type
application/json
{
  • "defaultTagValues":
    [
    ]
}

Response samples

Content type
application/json
Example
{
  • "defaultTagValues":
    [
    ],
  • "userId": "string"
}
Try it

Get user

Retrieve user default tag values applied to all user transactions.

path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "defaultTagValues":
    [
    ],
  • "userId": "string"
}
Try it

Delete user

Delete a user and all associated data. Warning: this operation is irreversible.

path Parameters
userId
required
string

Responses

transactions

Try it

Calculate carbon footprints

Calculate the carbon footprints of the input transactions

Request Body schema: application/json
required
Array of objects (InputTransaction)

List of the user transactions.

userId
required
string

Id of the user owning the transactions.

Responses

Request samples

Content type
application/json
{
  • "transactions":
    [
    ],
  • "userId": "string"
}

Response samples

Content type
application/json
Example
[ ]