Getting Started with Nectar

Learn all about Nectar's API built for carbon accounting solutions and ESG platforms.

Overview

Welcome to the Nectar API guide! Use this guide to query your utility data and set up utility data collection via an iframe. Contact [email protected] or make an account on nectarclimate.com to request an API Key and get started.

"Nectar serves as a reliable and cost-effective technology solution to extract, store, and analyse sustainability data leading to enhanced reporting capabilities and streamlined workflows." -- Matthew Greening, Founder and Principal Director of NettZero

The Challenge of Utility Data Integrations

Utility data collection stands as one of the biggest blockers towards rapid decarbonization. After helping automate sustainability data initiatives at Fortune 500 companies across manufacturing, food & beverage, and logistics, we're making the Nectar API public to solve our partners' data challenges:

  • Carbon accounting platforms incur high operating costs via in-house or out-sourced labor
  • Environmental consultants face scalability challenges without using data automation
  • Companies doing their CDP report spend 100+ hours a year reading utility bills to record usage

Carbon accounting platforms and environmental consultants integrate the Nectar API to add automated utility data collection. Your clients connect their utility accounts once, and your platform gets up-to-date usage data forever.

Integrating Nectar with a Carbon Accounting Platform

The steps to integrate as a Carbon Accounting Platform to automate utility data collection for your customers are as follows:

  1. Work directly with the Nectar team to configure the company objects that your team will be managing and the sites for each company. We expose these endpoints in a private API after onboarding or an initial pilot.
  2. Display the Nectar utility connection page on your platform. Embed the client-side iframe onto your website with a valid magic link. When a utility account is connected using the magic link it is automatically associated with the company and site; see more here. Alternatively, you may choose to directly upload utility bills to Nectar via an API for processing; see more here.
  3. After utility accounts are connected by your client, use the Nectar API to query up-to-date utility usage. Filter by utility type, date, or location. See more here.

Featured API Users

Unravel Carbon

Unravel Carbon is an AI-powered decarbonization platform that helps companies measure, track, reduce, and report their carbon emissions. It measures a company's full supply chain carbon profile in seconds, generates reduction pathways and auto-populates regulatory disclosure reports. It is backed by Sequoia and Y Combinator, and is already serving global brands like SATS, Global Fashion Group, Mercedes Benz, and the Monetary Authority of Singapore.

Nettzero

NettZero provides sustainability consulting services to a diverse range of customers from industries spanning commercial property, to professional services, and manufacturing. Our customers need data to not only quantify their emissions but to accurately measure and manage utility consumption, waste generation, and their scope 3 sources. Nectar serves as a reliable and cost-effective technology solution to extract, store, and analyse sustainability data leading to enhanced reporting capabilities and streamlined workflows.

Root URL

Nectar external API’s root URL is https://external.nectarclimate.com/. Once you have your API keys from the Nectar team, make your first request using our ping endpoint.

curl --location --request GET 'https://external.nectarclimate.com/ping' \
--header 'X-API-Key: <YOUR_SECRET_KEY>'

Organization of database objects

Each API key corresponds to an admin user in the Nectar database. For most API users (carbon accounting platforms and environmental consultants), this key is provisioned to your entire team. Each key is associated with a collection of company objects. And each company has a list of sites which corresponds to facilities. And each facility can have a number of connected utility objects. Finally utility data is stored in our database as meterSiteUsageData objects.

Authorization

On your Nectar Settings page, you can find your api keys in the integration section. Requests made to external.nectarclimate.com to fetch up-to-date utility data require <YOUR_SECRET_KEY> while iframe integrations require a public hash to uniquely identify a valid company and site. Secret keys will always be passed through headers, while public hashes will be passed as url params.

The API secret key needs to be in a header of the form: X-API-Key: <YOUR_SECRET_KEY>.

Errors

The Nectar API returns standard HTTP error codes.

200OK: Your request was successful
400Bad Request -- Your request could not be parsed or is invalid.
401Unauthorized -- Your API key is missing or incorrect.
403Forbidden -- The resource requested is hidden for administrators only or doesn't exist.
404Not Found -- The resource requested does no exist.
429Too Many Requests -- Try again later.
500Internal Server Error -- We had a problem with our server. Try again later or contact support.
502Bad Gateway -- Your request timed out (exceeded 10 seconds).
503Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Note from our founders

Thanks for supporting Nectar and reading our docs. We started Nectar years ago to accelerate rapid decarbonization for corporations world-wide. Our priority is partnering with as many folks in the world to help you, your customers, and your partners access utility data. If you have questions or would like support integrating, please reach out to [email protected]. Happy hacking! -Allen & Katherine