NAV

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

Your refresh token is a longer-lived token that is used to 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"

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.

Transaction Categories

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

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:

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.