Introduction

Welcome to the Carbon Insights Documentation. This is a guide for usage of the Carbon Insights API.

If you have questions or need support, please contact tech@carboninsights.co.

Schema

All API access is over HTTPS, and accessed from https://api.carboninsights.co. All data is sent and received as JSON. You must include the Content-Type: application/json header when sending your requests.

Registration & Authentication

curl "https://api.carboninsights.co"
  -H "Authorization: Token YOUR_ACCESS_TOKEN"
  -H "Content-Type: application/json"

carbIN uses JSON Web Tokens to control access to the API. In order to send and receive data, you must first register for an account.

After successfully registering, you can request your authorization tokens. You will receive two tokens. Save these, but don't get too attached to them. They expire quickly for security purposes.

Your access token is a short-lived token that is sent in the header of every request:

Authorization: Token YOUR_ACCESS_TOKEN

You must replace YOUR_ACCESS_TOKEN with your personal access JWT you received upon registering for an account.

Your refresh token is a longer-lived token that is used to [request a new access token]#(request-a-new-access-token) when your access token expires.

When your refresh token expires, you will use your account credentials to reauthenticate and request a new set of tokens.

Request Ids

Each API request has an associated request id. You can find this value in the Request-Id response header. Referencing the request id is helpful when you need to contact us for support regarding a specific request.

Endpoints

Register for an account

Sample Request:

{
    "username": "ilovetheplanet",
    "password": "Sav3Th3Whal3s",
    "first_name": "jeff",
    "last_name": "whalen",
    "email": "jwhalen@bluebank.com"
}

Sample Response:

{
    "message": "Account with username ilovetheplanet created successfully. Use credentials to generate authorization token."
}

POST https://api.carboninsights.co/register

Query Parameters

Required

Parameter	Type	Description
`username`	`string`	The account username. Must be < 50 characters.
`password`	`string`	The account password. Must be distinct from username and > 7 characters.
`first_name`	`string`	The account holder first name. Must be < 50 characters.
`last_name`	`string`	The account holder last name. Must be < 50 characters.
`email`	`string`	The account email. Must be a valid email format.

Request authorization tokens

Sample Request:

{
    "username": "ilovetheplanet",
    "password": "Sav3Th3Whal3s"
}

Sample Response:

{
    "access": <YOUR_ACCESS_TOKEN>,
    "refresh": <YOUR_REFRESH_TOKEN>
}

POST https://api.carboninsights.co/token

Query Parameters

Required

Parameter	Type	Description
`username`	`string`	The account username. Must match registered account username.
`password`	`string`	The account password. Must match registered account password.

Request new access token

Sample Request:

{
    "refresh": <YOUR_REFRESH_TOKEN>
}

Sample Response:

{
    "access": <YOUR_NEW_ACCESS_TOKEN>
}

POST https://api.carboninsights.co/token/refresh

Query Parameters

Required

Parameter	Type	Description
`refresh`	`string`	Your refresh token received when initially requesting your authorization tokens.

Calculate a carbon score

Sample Request:

{
    "user_profile": {
        "diet": "typical",
        "renewable_energy": 0,
        "natural_gas": true,
        "shared_account": false,
        "zip_code": 19130,
        "fuel_grade": "regular"
    },
    "options": {
        "offsets": false,
        "recommendations": true,
        "CO2e": true,
        "land": false,
        "water": false,
        "category_type": "category",
        "country": "United States",
        "aggregate": true
    },
    "transactions": [
        {
            "date": "01-03-2020",
            "amount": 248.76,
            "category": "Air Travel", 
            "description": "Delta",
            "original_description": "Delta 866-576-1039 GA"
        },
                {
            "date": "2020-03-03",
            "amount": 73.88,
            "category": "Hotel", 
            "description": "Hilton",
            "original_description": "Hilton - WESTHEIM HOUSTON"
        },
                {
            "date": "2020-03-03",
            "amount": 11.23,
            "category": "Rental Car & Taxi", 
            "description": "Lyft",
            "original_description": "LYFT *RIDE SUN 12AM 855-865-9553 CA"
        }
    ]
}

Sample Response:

{
    "messages": [],
    "details": {
        "footprint": {
            "category": {
                "0": "Air Travel",
                "1": "Hotel",
                "2": "Rental Car & Taxi"
            },
            "CO2e Emissions [tonne]": {
                "0": 0.23864127230148421,
                "1": 0.021415030569301514,
                "2": 0.04303300299010413
            }
        },
        "recommendations": {
            "category": {
                "0": "One Less Flight",
                "1": "Driving 10% less"
            },
            "CO2e Emissions [tonne]": {
                "0": 0.23864127230148421,
                "1": 0.004303300299010413
            }
        }
    }
}

POST https://api.carboninsights.co/calculateCarbonScore

Query Parameters for `transactions`

Required

Parameter	Type	Description
`date`	`date string`	The transaction date. Format can be one of: `YYYY-MM-DD` `DD-MM-YYYY`
`amount`	`decimal`	The transaction amount in USD Note: negative amounts are treated as refunds and have negative emissions associated with them
`category`	`string`	The transaction category (category or Merchant Category Code (MCC))
`description`	`string`	Optional The transaction description
`original_description`	`string`	Optional The original description of the transaction

Query Parameters for `user_profile`

Optional

Parameter	Default	Description
`diet`	`"typical"`	The user's diet. Can be one of: `"typical"` `"vegetarian"` `"vegan"`
`renewable_energy`	`0`	The fraction of the user's eletricity that is renewable
`natural_gas`	`false`	Whether the user uses natural gas for heating and cooking
`shared_account`	`false`	Whether the user shares the account with at least one other person
`zip_code`	`00000`	The user's zip code
`fuel_grade`	`"regular"`	The user's car's fuel grade. Can be one of: `"regular"` `"mid_grade"` `"premium"` `"diesel"`

The default zip_code value indicates average US data will be used.

Query Parameters for `options`

Optional

Parameter	Default	Description
`offsets`	`false`	Whether to return an offset referral link
`recommendations`	`false`	Whether to return user recommendedations
`CO2e`	`true`	Whether to return CO2e emissions in response
`land`	`false`	Whether to return land use in response
`water`	`false`	Whether to return water use in response
`category_type`	`"category"`	Whether to use a category or Merchant Category Code (MCC) to categorize the transaction. Can be one of: `"category"` `"mcc"`
`country`	`"United States"`	Country used to determine economic and environmental data. We currently only provide full support for the United States.
`aggregate`	`false`	Whether to return an aggregated (by category or Merchant Category Code (MCC)) footprint or by footprints by transaction.

If you include the user_profile or options parent parameters, you are required to include all corresponding child parameters. Providing the data in user_profile improves the accuracy of the environmental footprint calculation. If it is not included, typical values for a US resident will be assumed.

Transaction Categories

Below is an exhaustive list of the transaction categories we currently support for computing emissions

Recommended Categories


`Air Travel` `Alcohol & Bars` `Allowance` `Amusement` `Arts` `ATM Fee` `Baby Supplies` `Babysitter & Daycare` `Bank Fee` `Bonus` `Books & Supplies` `Books` `Cash & ATM` `Charity` `Check` `Child Support` `Clothing` `Coffee Shops` `Credit Card Payment` `Dentist` `Doctor` `Electronics & Software` `Eyecare` `Fast Food` `Federal Tax` `Finance Charge`	`Financial Advisor` `Furnishings` `Gift` `Groceries` `Gym` `Hair` `Health Insurance` `Hobbies` `Home Improvement` `Home Insurance` `Home Services` `Home Supplies` `Hotel` `Interest Income` `Investments` `Kids Activities` `Late Fee` `Laundry` `Lawn & Garden` `Life Insurance` `Local Tax` `Misc Expenses` `Mortgage & Rent` `Movies & DVDs` `Music` `Newspapers & Magazines`	`Paycheck` `Pet Food & Supplies` `Pet Grooming` `Pharmacy` `Printing` `Property Tax` `Reimbursement` `Rental Car & Taxi` `Rental Income` `Renturned Purchase` `Restaurants` `Sales Tax` `Service Fee` `Shipping` `Spa & Massage` `Sporting Goods` `Sports` `State Tax` `Student Loan` `Toys` `Trade Commissions` `Transfer for Cash Spending` `Tuition` `Vacation` `Veterinary`

Additional Categories


`Auto & Transport` `Bills & Utilities` `Business Services` `Education` `Entertainment` `Fees & Charge` `Financial`	`Food & Dining` `Gifts & Donations` `Health & Fitness` `Home` `Income` `Investments` `Kids` `Misc Expenses`	`Personal Care` `Pets` `Shopping` `Taxes` `Transfer` `Travel` `Uncategorized`

Throttling

The Carbon Insights API currently specifies the following request rate limits for authenticated users:

Per Second: 30
Per Minute: 400
Per Day: 100000

Errors

The Carbon Insights API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your JWT Token is incorrect.
405	Method Not Allowed -- You tried to access an endpoint with an invalid method.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
429	Too Many Requests -- You've exceeded the request limit for your account.

Introduction

Schema

Registration & Authentication

Request Ids

Endpoints

Register for an account

Query Parameters

Request authorization tokens

Query Parameters

Request new access token

Query Parameters

Calculate a carbon score

Query Parameters for transactions

Query Parameters for user_profile

Query Parameters for options

Transaction Categories

Recommended Categories

Additional Categories

Throttling

Errors

Query Parameters for `transactions`

Query Parameters for `user_profile`

Query Parameters for `options`