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.

Authentication

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

carbIN uses JSON Web Tokens to allow access to the API. If you are interested in applying for a token, please contact tech@carboninsights.co.

carbIN requires that the JWT is included in all API requests to the server in a header that looks like the following:

Authorization: Token YOUR_TOKEN

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

Calculate a carbon score

Sample Request:

{
    "user_profile": {
        "diet": "vegetarian",
        "VRE": 0,
        "natural_gas": false,
        "shared_account": false, 
        "zip_code": 19130
    },
    "options": {
        "offsets": false,
        "recommendations": true,
        "CO2e": true,
        "land": false,
        "water": false
    },
    "transactions": [
        {
            "date": "2020-03-01",
            "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.22999763029727627,
                "1": 0.02183167856093383,
                "2": 0.04184753435490269
            }
        },
        "recommendations": {
            "category": {
                "0": "One Less Flight",
                "1": "Driving 10% less"
            },
            "CO2e Emissions [tonne]": {
                "0": 0.22999763029727627,
                "1": 0.004184753435490269
            }
        }
    }
}

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
description string 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"
VRE 0 The fraction of the user's eletricity that is green
natural_gas false Whether the user uses natural gas for heating and cooling
shared_account false Whether the user shares the account with at least one other person
zip_code 00000 The user's zip code

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 user CO2 footprint in response
land false Whether to return land use in response
water false Whether to return water use in response

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.