For Developers 5 Jun 2019

How Cloverly's API Offset Match Works

People and entities have different preferences for sources of carbon avoidance or carbon offsets. Because of this, Cloverly does two things: 1) provide a set of carbon offset sources that’s diverse in location and type, and 2) extend the ability to target your offsets at specific sources.

Photo of a map and compass to illustrate a blog post about how Cloverly's API matches carbon offsets for location or specific carbon-offset sources as well as other factors
Photo by Ylanite Koppens on Pexels

We will describe how to use the ability to target your offsets at specific sources. If you want to target the closest wind energy to Brooklyn, New York, then include this payload in your API call:

"offset_match": {"location": {"zip": "11223"}, "type": "wind"}}

But first, about the transparency:

Which Source Offsets Your Carbon?

One of our beliefs is that we want to bring transparency to environmental markets. When making a purchase with Cloverly’s API or requesting an estimate, the API returns to you the source of the offset. This will be returned in the offset attribute in the JSON payload. It looks like the following:

 "offset": {         "city": "Passadumkeag",         "country": "United States",         "latlng": {             "x": 45.1299212,             "y": -68.3515483         },         "name": "Passadumkeag Wind Farm - unknown",         "offset_type": "wind",         "pretty_url": "",         "province": "Maine",         "slug": "passadumkeag-wind-farm-e6c30c",         "technical_details": "The project consists of 13, V112-3.3 MW wind turbines\r\nmanufactured by Vestas-American Wind Technology\r\nInc. Each turbine is mounted on top of an 84-meter-tall tower and will have a 112-meter, three-blade rotor\r\nconnected to a generator. The AC power from the\r\ngenerator will be modulated at 60 hz by a converter.\r\nMultiple wind turbines will be electrically connected\r\nin parallel to the main power transformer where the\r\nenergy will be converted from 34.5kV to 115kV for\r\ninterconnection.",         "total_capacity": "50 MW”     }

Offset Matching by Low Cost

If no arguments are provided to the offset_match attribute, the Cloverly API will match on lowest price. This is a global search for low price, so the offset returned may be at a distant location. We live on a globe, and one side of the earth affects the other. For some cases, this may be a suitable alternative.

Offset Matching by Location

YIMBY (yes in my back yard) is a good thing, when it’s a good thing. When the Cloverly API returns an offset, it will include the latitude/longitude location of the offset.

In requests, use a location object in the offset_match to sort offsets by the closest. The following examples show two ways to match by location:

  • "offset_match": {"location":{"postal_code": "11223", "country": "US" }}
  • offset_match": {"location":{"latlng": [30.2954742,-86.0602712]}}

Offset Matching by Offset Type

You may have a preference for wind, solar, biomass, or any of the other ways to offset carbon emissions. When Cloverly returns an offset, it will include type, which can be various different sources of carbon offsets.

In requests, use a type object in the offset_match to sort offsets by type.

  • "offset_match": {"type":"wind"}
  • "offset_match": {"type":"solar"}
  • "offset_match": {"type":"biomass"}

We are aggressively adding more types.

Offset Matching by Specific Asset

Some use cases like to give the end customer an option to choose the offset. Use the API’s offsets endpoint to list all of the available offsets.

Then you can use an offset’s slug to target a specific source for offsets.

• "offset_match": {"slug":"passadumkeag-wind-farm-e6c30c"}
• "offset_match": {"slug":"utah-sited-solar-716404"}
• "offset_match": {"slug":"virginia-sited-solar-ddff60"}

Combining Matches

The code also allows combining parameters into a single query. To find the closest wind energy to Brooklyn, you can use the following offset_match as part of your call:

"offset_match": {"type":"wind", "location":{"postal_code": "11223", "country": "US" }} 

Our API Philosophy

We are consolidating all offset matching functions under that attribute.  That allows us to use the slugtype, and location matching algorithms without adding additional top-level attributes.

Full Example

A full API call with offset matching would look like this:

curl \ -X POST \ -d '{"from":{"zip":"35209"},"to":{"zip":"94043"},"weight":{"value":94,"units":"kg"}, "offset_match": {"type":"wind", "location":{"postal_code": "11223", "country": "US" }}}' \ -H "Content-type: application/json" \ -H "Authorization: Bearer public_key:47800ea0ee541b4c"

• • •

Carbon-Neutral Shipping with Cloverly

Cloverly provides an easy way for ecommerce consumers to purchase carbon offsets and achieve carbon-neutral shipping for their orders, at no cost to the store owner. For details, visit our How It Works page. Shopify store owners can get our Shopify shipping app by clicking here. For our BigCommerce app, click here. If you have a Magento store, click here.

Cloverly Team