Nectar API: Utility data and companies

Query up-to-date utility data by company and dates

How it works

After onboarding with the Nectar team, you will be able to configure companies and sites that your platform manages via a private API or directly with the Nectar team. You'll get access to an API secret key, which is required in all requests as a header of the form X-API-Key: <YOUR_SECRET_KEY>.

Typically, you'll use GET endpoints to query the ids and information of sites and companies to use in additional queries. On a regular basis, you'll mainly use endpoints to query usage data in meterSiteUsageData objects. Finally, there is an endpoint to generate a valid magic link that is required for the client-side iframe integration. All endpoints area REST API endpoints served by a Django backend.

All usage data in meterSiteUsageData are returned with a documentId field. The documentId can be used to download the original document / bill and also be used to view the document's audit trail on Nectar's platform.

Finally, Nectar also exposes an API endpoint upload documents directly to be processed. When the processing job finishes, a documentId is returned.

Get all companies

Get all companies that your API key is associated with.

Request URL
GET https://external.nectarclimate.com/companies

Request Params

None

Request Body

None

Sample Request

curl --location --request GET 'https://external.nectarclimate.com/companies' \
--header 'X-API-Key: <YOUR_SECRET_KEY>'
var myHeaders = new Headers();
myHeaders.append("X-API-Key", "<YOUR_SECRET_KEY>");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://external.nectarclimate.com/companies", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response Body

  • companies (array of Company objects): companies associated with the API key
    • id (string): unique identifier for the company
    • name (string): name of the company
    • firstYear (number): the earliest year for data collection for the company, used to determine volume of historical data collected from online utility connections.
    • sites (array of Site objects): sites associated with the company
      • id (string): unique identifier of the site
      • name (string): name of the site
      • address (string): address of the site
      • externalId (string): external or secondary id of the site used for external reference, exports, and data integrations
      • path (array of strings): location filters for the site from most general to most specific. E.g. ["US", "East", "New York"]

Create a company

Create a new company that your API key is associated with

Request URL
POST https://external.nectarclimate.com/companies

Request Params

None

Request Body

  • name (string, required): name of the company
  • firstYear (number, required): the earliest year for data collection for the company, used to determine volume of historical data collected from online utility connections.

Sample Request

curl --location --request POST 'https://external.nectarclimate.com/companies' \
--header 'X-API-Key: <YOUR_SECRET_KEY>'
--data-raw '{
    "name": "New Company Name",
    "firstYear": 2020,
}'
var myHeaders = new Headers();
myHeaders.append("X-API-Key", "<YOUR_SECRET_KEY>");

var raw = JSON.stringify({"name": "New Company Name","firstYear":2020});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://external.nectarclimate.com/companies", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response Body

  • companies (array of Company objects): companies associated with the API key
    • id (string): unique identifier for the company
    • name (string): name of the company
    • firstYear (number): the earliest year for data collection for the company, used to determine volume of historical data collected from online utility connections.
    • sites (array of Site objects): sites associated with the company
      • id (string): unique identifier of the site
      • name (string): name of the site
      • address (string): address of the site
      • externalId (string): external or secondary id of the site used for external reference, exports, and data integrations
      • path (array of strings): location filters for the site from most general to most specific. E.g. ["US", "East", "New York"]

Get all sites by company

Gets all the sites related to a specific company

Request URL
GET https://external.nectarclimate.com/company/<company_id>/sites

Request Params

  • <company_id> (string, required): id of the company used for querying

Request Body

None

Sample Request

curl --location --request GET 'https://external.nectarclimate.com/company/<company_id>/sites' \
--header 'X-API-Key: <YOUR_SECRET_KEY>'
var myHeaders = new Headers();
myHeaders.append("X-API-Key", "<YOUR_SECRET_KEY>");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://external.nectarclimate.com/company/<company_id>/sites", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response Body

  • sites (array of Site objects): sites associated with the company
    • id (string): unique identifier of the site
    • name (string): name of the site
    • address (string): address of the site
    • externalId (string): external or secondary id of the site used for external reference, exports, and data integrations
    • path (array of strings): location filters for the site from most general to most specific. E.g. ["US", "East", "New York"]

Create a site

Create a site related to a specific company

Request URL
POST https://external.nectarclimate.com/company/<company_id>/sites

Request Params

  • <company_id> (string, required): id of the company associated to the site

Request Body

  • name (string, required): name of the site
  • address (string, required): address of the site
  • externalId (string, optional): external or secondary id of the site used for external reference, exports, and data integrations
  • path (array of strings, required): location filters for the site from most general to most specific. E.g. ["US", "East", "New York"]

Sample Request

curl --location --request POST 'https://external.nectarclimate.com/company/<company_id>/sites' \
--header 'X-API-Key: <YOUR_SECRET_KEY>'
--data-raw '{
    "name": "New Site Name",
    "address": "1234 Main Street, Boston, MA, 02139 USA",
    "externalId": "234y7923", 
    "path": ["US", "East"],
}'
var myHeaders = new Headers();
myHeaders.append("X-API-Key", "<YOUR_SECRET_KEY>");

var raw = JSON.stringify({"name": "New Site Name","address":"1234 Main Street, Boston, MA, 02139 USA", "externalId": "234y7923", "path":["US", "East"]});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://external.nectarclimate.com/company/<company_id>/sites", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response Body

  • id (string): unique identifier of the site
  • name (string): name of the site
  • address (string): address of the site
  • externalId (string): external or secondary id of the site used for external reference, exports, and data integrations
  • path (array of strings): location filters for the site from most general to most specific. E.g. ["US", "East", "New York"]

Modify a site

Modify the fields for a site

Request URL
PATCH https://external.nectarclimate.com/site/<site_id>

Request Params

  • <site_id> (string, required): id of the site being modified

Request Body

  • name (string, optional): name of the site
  • address (string, optional): address of the site
  • externalId (string, optional): external or secondary id of the site used for external reference, exports, and data integrations
  • path (array of strings, optional): location filters for the site from most general to most specific. E.g. ["US", "East", "New York"]

Sample Request

curl --location --request PATCH 'https://external.nectarclimate.com/site/<site_id>' \
--header 'X-API-Key: <YOUR_SECRET_KEY>'
--data-raw '{
    "name": "New Site Name",
    "address": "1234 Main Street, Boston, MA, 02139 USA",
    "externalId": "234y7923", 
    "path": ["US", "East"],
}'
var myHeaders = new Headers();
myHeaders.append("X-API-Key", "<YOUR_SECRET_KEY>");

var raw = JSON.stringify({"name": "New Site Name","address":"1234 Main Street, Boston, MA, 02139 USA", "externalId": "234y7923", "path":["US", "East"]});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://external.nectarclimate.com/site/<site_id>", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response Body

  • id (string): unique identifier of the site
  • name (string): name of the site
  • address (string): address of the site
  • externalId (string): external or secondary id of the site used for external reference, exports, and data integrations
  • path (array of strings): location filters for the site from most general to most specific. E.g. ["US", "East", "New York"]

Query usage data by site

Query all the meterSiteUsageData associated to a site on page <page_num>. Note that all usage data collected from utility accounts is stored in meterSiteUsageData objects and the page size is 50. Any usage data that contains days within the startDate to endDate period inclusive is returned.

Request URL
POST https://external.nectarclimate.com/site/<site_id>/usage?page=<page_num>

Request Params

  • <site_id> (string, required): id of the site used for querying
  • <page_num>(int, optional): page number of result, defaults to 1

Request Body

  • datasourceType(array of string, required): required enum type of data queried, must be a sublist of ["ELECTRICITY", "GAS", "WATER", "FUEL", "SOLAR", "WASTE", "TELECOM"]
  • startDate (string, required): required YYYYMMDD string startDate for the usage (inclusive)
  • endDate (string, required): YYYYMMDD string endDate for the usage (inclusive)

Sample Request

curl --location --request POST 'https://external.nectarclimate.com/site/<site_id>/usage?page=<page_num>' \
--header 'X-API-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datasourceType": ["ELECTRICITY", "GAS"],
    "startDate": "20230101",
    "endDate": "20231231"
}'
var myHeaders = new Headers();
myHeaders.append("X-API-Key", "<YOUR_SECRET_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({"datasourceType":["ELECTRICITY","GAS"],"startDate":"20230101","endDate":"20231231"});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://external.nectarclimate.com/site/<site_id>/usage?page=<page_num>", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response Body

  • totalMeterSiteUsageData (int): the total number of meterSiteUsageData in the given query
  • perPage (int): the page size
  • totalPages (int): the total number of pages
  • currentPage (int): the current page number
  • hasNext (boolean): has a next page
  • hasPrevious (boolean): has a previous page
  • meterSiteUsageData (array of meterSiteUsageData objects): meterSiteUsageData records on the current page
    • id (string): unique identifier for each record, automatically generated
    • created (string): timestamp indicating when the record was created, automatically set at creation time
    • updated (string): timestamp of the last update to the record, automatically set each time the record is updated
    • documentId (string): id of the document containing the
    • auditTrailUrl (string): url of the meter's audit trail on Nectar's platform
    • siteId (string): id of the site associated with the record
    • siteName (string): name of the site associated with the record
    • siteExternalId (string, optional): external id the site associated with the record
    • siteAddress (string): address of the site associated with the record
    • datasourceType (string): specifies the type of data source, one of "ELECTRICITY", "GAS", "WATER", "FUEL", "WASTE", "TELECOM"
    • startDate (string): start date for the usage or charge period as a timestamp
    • endDate (string): end date for the usage or charge period as a timestamp
    • totalCharges (string): total monetary charges incurred on the invoice for usage across all meters in the document as a decimal (note all decimals and floating points are sent as strings to preserve precision)
    • totalChargesUnits (string): currency code for total charges
    • usage (string): usage amount extracted from billing data. Note: when meter is solar data (given by the isSolar field below) the amount is the kWh produced
    • usageUnits (string): units for usage
    • exclusion (boolean): indicates if data should be excluded in aggregation calculations
    • isEstimated (boolean): indicates if the data has been estimated
    • accountId (string, optional): accountID associated with usage, blank if not present on bill
    • meterId (string, optional): meterId associated with usage, blank if not present on bill
    • meterDescription (string, optional): meterDescription associated with usage, blank if not present on bill
    • submeterId (string, optional): submeterId associated with usage, blank if not present on bill
    • currentReading (string, optional): current reading associated with the meter, blank if not present on bill
    • previousReading (string, optional): previous reading associated with the meter, blank if not present on bill
    • meterReadingUnits (string, optional): units associated with meter reading, blank if not present on bill
    • shopNumber (string, optional): shopNumber associated with usage, blank if not present on bill
    • nmi (string, optional): nmi associated with usage, blank if not present on bill
    • mirn (string, optional): mirn associated with usage, blank if not present on bill
    • zipcode (string, optional): the zipcode of the transaction and usage, optional
    • state (string, optional): state of the transaction and usage, optional
    • electricityFields (object, optional, present only in electricity transactions): additional fields for electricity data
      • isSolar (boolean, optional): flag indicating solar energy production (usage = produced electricity), optional
      • fractionRenewable (string, optional): fraction of energy sourced from renewable resources, optional. String represents a decimal between 0 and 1 inclusive
      • virtualNetMeteringGeneratedKwh (string, optional): amount of total kWh of electricity generated from solar
      • virtualNetMeteringAppliedKwh (string, optional): amount of kWh of electricity consumed from net metering
      • virtualNetMeteringExcessKwh (string, optional): amount of kWh of electricity remaining, net of electricity consumed
      • networkPeakUsageKwh (string, optional): peak usage associated with the network in kWh
      • networkOffPeakUsageKwh (string, optional): off-peak usage associated with the network in kWh
      • networkShoulderUsageKwh (string, optional): shoulder usage associated with the network in kWh
      • peakDemand (string, optional): peak demand of electricity meter
      • peakDemandUnits (string, optional): units of peak demand
    • waterFields (object, optional, present only in water transactions): additional fields for water data
      • waterType (string, optional): type of water used, optional with predefined choices
      • meterHighLow (string, optional): indicates if the meter type is "HIGH" or "LOW"
    • fuelFields (object, optional, present only in fuel transactions): additional fields for fuel data
      • fuelType (string, optional): type of fuel used, optional with predefined choices
      • distanceTraveled (string, optional): distance traveled if data is associated with a vehicle and milage
      • distanceTraveledUnits (string, optional): distance traveled for fuel consumption
      • cargoWeight (string, optional): weight of the cargo if data is associated with cargo
      • cargoWeightUnits (string, optional): units of cargo weight
    • wasteFields (object, optional, present only in waste transactions): additional fields for waste data
      • wasteState (string, optional): state of waste, either "SOLID" or "LIQUID"
      • wasteType (string, optional): type of waste associated from predefined choices
      • wasteStream (string, optional): stream of waste associated from predefined choices
      • numBins(string, optional): number of bins associated with usage
      • binSize (string, optional): size of bins associated with usage
      • binSizeUnits (string, optional): units for the bin sizes associated with usage

Query usage data by company

Query all the meterSiteUsageData associated to a company on page <page_num>. Note that all usage data collected from utility accounts is stored in meterSiteUsageData objects and the page size is 50. Any usage data that contains days within the startDate to endDate period inclusive is returned.

Request URL
POST https://external.nectarclimate.com/company/<company_id>/usage?page=<page_num>

Request Params

  • <company_id> (string, required): id of the company used for querying
  • <page_num>(int, optional): page number of result, defaults to 1

Request Body

  • datasourceType(array of string, required): required enum type of data queried, must be a sublist of ["ELECTRICITY", "GAS", "WATER", "FUEL", "SOLAR", "WASTE", "TELECOM"]
  • startDate (string, required): required YYYYMMDD string startDate for the usage (inclusive)
  • endDate (string, required): YYYYMMDD string endDate for the usage (inclusive)

Sample Request

curl --location --request POST 'https://external.nectarclimate.com/company/<company_id>/usage?page=<page_num>' \
--header 'X-API-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datasourceType": ["ELECTRICITY", "GAS"],
    "startDate": "20230101",
    "endDate": "20231231"
}'
var myHeaders = new Headers();
myHeaders.append("X-API-Key", "<YOUR_SECRET_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({"datasourceType":["ELECTRICITY","GAS"],"startDate":"20230101","endDate":"20231231"});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://external.nectarclimate.com/company/<company_id>/usage?page=<page_num>", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response Body

This response body is identical to the body in the request to query by site

  • totalMeterSiteUsageData (int): the total number of meterSiteUsageData in the given query
  • perPage (int): the page size
  • totalPages (int): the total number of pages
  • currentPage (int): the current page number
  • hasNext (boolean): has a next page
  • hasPrevious (boolean): has a previous page
  • meterSiteUsageData (array of meterSiteUsageData objects): meterSiteUsageData records on the current page
    • id (string): unique identifier for each record, automatically generated
    • created (string): timestamp indicating when the record was created, automatically set at creation time.
    • updated (string): timestamp of the last update to the record, automatically set each time the record is updated.
    • documentId (string): id of the document containing the
    • auditTrailUrl (string): url of the meter's audit trail on Nectar's platform
    • siteId (string): id of the site associated with the record
    • siteName (string): name of the site associated with the record
    • siteExternalId (string, optional): external id the site associated with the record
    • siteAddress (string): address of the site associated with the record
    • datasourceType (string): specifies the type of data source, one of "ELECTRICITY", "GAS", "WATER", "FUEL", "WASTE", "TELECOM"
    • startDate (string): start date for the usage or charge period as a timestamp
    • endDate (string): end date for the usage or charge period as a timestamp
    • charges (string): total monetary charges incurred on the invoice for usage across all meters as a decimal (note all decimals and floating points are sent as strings to preserve precision)
    • chargesUnits (string): currency code for charges
    • usage (string): usage amount extracted from billing data. Note: when meter is solar data (given by the isSolar field below) the amount is the kWh produced
    • usageUnits (string): units for usage
    • exclusion (boolean): indicates if data should be excluded in aggregation calculations
    • isEstimated (boolean): indicates if the data has been estimated
    • accountId (string, optional): accountID associated with usage, blank if not present on bill
    • meterId (string, optional): meterId associated with usage, blank if not present on bill
    • meterDescription (string, optional): meterDescription associated with usage, blank if not present on bill
    • submeterId (string, optional): submeterId associated with usage, blank if not present on bill
    • currentReading (string, optional): current reading associated with the meter, blank if not present on bill
    • previousReading (string, optional): previous reading associated with the meter, blank if not present on bill
    • meterReadingUnits (string, optional): units associated with meter reading, blank if not present on bill
    • shopNumber (string, optional): shopNumber associated with usage, blank if not present on bill
    • nmi (string, optional): nmi associated with usage, blank if not present on bill
    • mirn (string, optional): mirn associated with usage, blank if not present on bill
    • zipcode (string, optional): the zipcode of the transaction and usage, optional
    • state (string, optional): state of the transaction and usage, optional
    • electricityFields (object, optional, present only in electricity transactions): additional fields for electricity data
      • isSolar (boolean, optional): flag indicating solar energy production (usage = produced electricity), optional
      • fractionRenewable (string, optional): fraction of energy sourced from renewable resources, optional. String represents a decimal between 0 and 1 inclusive
      • virtualNetMeteringGeneratedKwh (string, optional): amount of total kWh of electricity generated from solar
      • virtualNetMeteringAppliedKwh (string, optional): amount of kWh of electricity consumed from net metering
      • virtualNetMeteringExcessKwh (string, optional): amount of kWh of electricity remaining, net of electricity consumed
      • networkPeakUsageKwh (string, optional): peak usage associated with the network in kWh
      • networkOffPeakUsageKwh (string, optional): off-peak usage associated with the network in kWh
      • networkShoulderUsageKwh (string, optional): shoulder usage associated with the network in kWh
      • peakDemand (string, optional): peak demand of electricity meter
      • peakDemandUnits (string, optional): units of peak demand
    • waterFields (object, optional, present only in water transactions): additional fields for water data
      • waterType (string, optional): type of water used, optional with predefined choices
      • meterHighLow (string, optional): indicates if the meter type is "HIGH" or "LOW"
    • fuelFields (object, optional, present only in fuel transactions): additional fields for fuel data
      • fuelType (string, optional): type of fuel used, optional with predefined choices
      • distanceTraveled (string, optional): distance traveled if data is associated with a vehicle and milage
      • distanceTraveledUnits (string, optional): distance traveled for fuel consumption
      • cargoWeight (string, optional): weight of the cargo if data is associated with cargo
      • cargoWeightUnits (string, optional): units of cargo weight
    • wasteFields (object, optional, present only in waste transactions): additional fields for waste data
      • wasteState (string, optional): state of waste, either "SOLID" or "LIQUID"
      • wasteType (string, optional): type of waste associated from predefined choices
      • wasteStream (string, optional): stream of waste associated from predefined choices
      • numBins(string, optional): number of bins associated with usage
      • binSize (string, optional): size of bins associated with usage
      • binSizeUnits (string, optional): units for the bin sizes associated with usage

Post a document for processing

Submits a document to Nectar to be processed for a specific company. This endpoint returns a jobId that can be used to check the document's status. Note that since this endpoint requires a file upload, the request body must be form-data. The size limit for the utility bill is 10MB.

Request URL
POST https://external.nectarclimate.com/document

Request Params

None

Request Body (Form-data)

Unlike other Nectar endpoints, the body of this request must be form-data to allow for file submission.

  • companyId (string, required): id of the company associated with the document
  • document (file, required): File (up to 10MB) that will be processed by Nectar (pdf, png, jpg accepted)

Sample Request

curl --location 'https://external.nectarclimate.com/document' \
--header 'X-API-Key: <YOUR_SECRET_KEY>' \
--form 'companyId="2876fd83-10d5-4381-afac-868b4ca2fae6"' \
--form 'document=@"/path/to/file"'
const myHeaders = new Headers();
myHeaders.append("X-API-Key", "<YOUR_SECRET_KEY>");

const formdata = new FormData();
formdata.append("companyId", "2876fd83-10d5-4381-afac-868b4ca2fae6");
formdata.append("document", fileInput.files[0], "file");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: formdata,
  redirect: "follow"
};

fetch("https://external.nectarclimate.com/document", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Response Body

  • jobId (string): job id for the document submission, used to track the progress of the document

Get status of job

Gets the status and details of a job given a job id. The status will always be one of "pending", "completed", or "failed". In general jobs will not fail due to retry policies. However, when a job does show "failed" as the status, please get in touch with our team at [email protected].

When the job is completed, this endpoint will also return the id of the parsed documents. These ids can be used to download the original document and are associated with meterSiteUsageData returned in the usage endpoints.

Request URL
GET https://external.nectarclimate.com/job/<job_id>

Request Params

  • job_id (string, required): the id of the job returned when posting a document to Nectar

Request Body

None

Sample Request

curl --location 'https://external.nectarclimate.com/job/<job_id>' \
--header 'X-API-KEY: <YOUR_SECRET_KEY>'
const myHeaders = new Headers();
myHeaders.append("X-API-KEY", "<YOUR_SECRET_KEY>");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow"
};

fetch("https://external.nectarclimate.com/job/<job_id>", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Response Body

  • status (string): indicates the status of the job, one of "pending", "failed", and "completed"
  • parsedDocumentIds (array of string, optional): list of document ids of completed documents. This field will only be present if status is "completed".
  • duplicates (int, optional): number of duplicates detected in the job. This field will only be present if status is "completed" and is the length of duplicateDocumentIds.
  • duplicateDocumentIds (array of string, optional): list of document ids of previously parsed documents identical to those in the job. This field will only be present if status is "completed".

Get document parsed results and original file

Get the parsed results for a document and a presigned S3 url for the original file given the document's id. The document's id is present for each entry in usage endpoints as documentId. The documentId is also returned by the job status endpoint after a job is completed in parsedDocumentIds. If this document has no corresponding file (in the case where the data was manually entered on the Nectar platform), this endpoint will resolve in a 404.

Request URL
GET https://external.nectarclimate.com/document/<document_id>

Request Params

  • document_id (string, required): the id of the document (can be found associated with usage or returned by the job status endpoint)

Request Body

None

Sample Request

curl --location 'https://external.nectarclimate.com/document/<document_id>' \
--header 'X-API-KEY: <YOUR_SECRET_KEY>'
const myHeaders = new Headers();
myHeaders.append("X-API-KEY", "<YOUR_SECRET_KEY>");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow"
};

fetch("https://external.nectarclimate.com/document/<document_id>", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Response Body

  • id: id of the document
  • created: timestamp of when the document was parsed completely
  • url (string, optional): presigned S3 url of the original document, can be used to download and view file directly. Expires within 24 hours. None if no file associated with document (e.g. this happens in the case of manual data entries).
  • notes(string, optional): any notes or assumptions made about document parsing or estimates
  • company: company object associated with the document
    • id (string): unique identifier for the company
    • name (string): name of the company
    • firstYear (number): the earliest year for data collection for the company, used to determine volume of historical data collected from online utility connections.
    • sites (array of Site objects): sites associated with the company
      • id (string): unique identifier of the site
      • name (string): name of the site
      • address (string): address of the site
      • externalId (string): external or secondary id of the site used for external reference, exports, and data integrations
      • path (array of strings): location filters for the site from most general to most specific. E.g. ["US", "East", "New York"]
  • meterSiteUsageData (array of meterSiteUsageData objects): meterSiteUsageData records on the current page
    • id (string): unique identifier for each record, automatically generated
    • created (string): timestamp indicating when the record was created, automatically set at creation time
    • updated (string): timestamp of the last update to the record, automatically set each time the record is updated
    • documentId (string): id of the document containing the
    • auditTrailUrl (string): url of the meter's audit trail on Nectar's platform
    • siteId (string): id of the site associated with the record
    • siteName (string): name of the site associated with the record
    • siteExternalId (string, optional): external id the site associated with the record
    • siteAddress (string): address of the site associated with the record
    • datasourceType (string): specifies the type of data source, one of "ELECTRICITY", "GAS", "WATER", "FUEL", "WASTE", "TELECOM"
    • startDate (string): start date for the usage or charge period as a timestamp
    • endDate (string): end date for the usage or charge period as a timestamp
    • totalCharges (string): total monetary charges incurred on the invoice for usage across all meters in the document as a decimal (note all decimals and floating points are sent as strings to preserve precision)
    • totalChargesUnits (string): currency code for total charges
    • usage (string): usage amount extracted from billing data. Note: when meter is solar data (given by the isSolar field below) the amount is the kWh produced
    • usageUnits (string): units for usage
    • exclusion (boolean): indicates if data should be excluded in aggregation calculations
    • isEstimated (boolean): indicates if the data has been estimated
    • accountId (string, optional): accountID associated with usage, blank if not present on bill
    • meterId (string, optional): meterId associated with usage, blank if not present on bill
    • meterDescription (string, optional): meterDescription associated with usage, blank if not present on bill
    • submeterId (string, optional): submeterId associated with usage, blank if not present on bill
    • currentReading (string, optional): current reading associated with the meter, blank if not present on bill
    • previousReading (string, optional): previous reading associated with the meter, blank if not present on bill
    • meterReadingUnits (string, optional): units associated with meter reading, blank if not present on bill
    • shopNumber (string, optional): shopNumber associated with usage, blank if not present on bill
    • nmi (string, optional): nmi associated with usage, blank if not present on bill
    • mirn (string, optional): mirn associated with usage, blank if not present on bill
    • zipcode (string, optional): the zipcode of the transaction and usage, optional
    • state (string, optional): state of the transaction and usage, optional
    • electricityFields (object, optional, present only in electricity transactions): additional fields for electricity data
      • isSolar (boolean, optional): flag indicating solar energy production (usage = produced electricity), optional
      • fractionRenewable (string, optional): fraction of energy sourced from renewable resources, optional. String represents a decimal between 0 and 1 inclusive
      • virtualNetMeteringGeneratedKwh (string, optional): amount of total kWh of electricity generated from solar
      • virtualNetMeteringAppliedKwh (string, optional): amount of kWh of electricity consumed from net metering
      • virtualNetMeteringExcessKwh (string, optional): amount of kWh of electricity remaining, net of electricity consumed
      • networkPeakUsageKwh (string, optional): peak usage associated with the network in kWh
      • networkOffPeakUsageKwh (string, optional): off-peak usage associated with the network in kWh
      • networkShoulderUsageKwh (string, optional): shoulder usage associated with the network in kWh
      • peakDemand (string, optional): peak demand of electricity meter
      • peakDemandUnits (string, optional): units of peak demand
    • waterFields (object, optional, present only in water transactions): additional fields for water data
      • waterType (string, optional): type of water used, optional with predefined choices
      • meterHighLow (string, optional): indicates if the meter type is "HIGH" or "LOW"
    • fuelFields (object, optional, present only in fuel transactions): additional fields for fuel data
      • fuelType (string, optional): type of fuel used, optional with predefined choices
      • distanceTraveled (string, optional): distance traveled if data is associated with a vehicle and milage
      • distanceTraveledUnits (string, optional): distance traveled for fuel consumption
      • cargoWeight (string, optional): weight of the cargo if data is associated with cargo
      • cargoWeightUnits (string, optional): units of cargo weight
    • wasteFields (object, optional, present only in waste transactions): additional fields for waste data
      • wasteState (string, optional): state of waste, either "SOLID" or "LIQUID"
      • wasteType (string, optional): type of waste associated from predefined choices
      • wasteStream (string, optional): stream of waste associated from predefined choices
      • numBins(string, optional): number of bins associated with usage
      • binSize (string, optional): size of bins associated with usage
      • binSizeUnits (string, optional): units for the bin sizes associated with usage

Get a valid magic link

Generates a Nectar signed secret for a specific site (which is assigned to a company beforehand during the onboarding process). Note that when magic links are displayed in the iframe integration, the company id is needed in addition to the signed secret.

Request URL
GET https://external.nectarclimate.com/magiclink/<site_id>

Request Params

  • <site_id> (string, required): id of the site that the secret will be associated with

Request Body

None

Sample Request

curl --location --request GET 'https://external.nectarclimate.com/magiclink/<site_id>' \
--header 'X-API-Key: <YOUR_SECRET_KEY>'
var myHeaders = new Headers();
myHeaders.append("X-API-Key", "<YOUR_SECRET_KEY>");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://external.nectarclimate.com/magiclink/<site_id>", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response Body

  • company_id (string): id of the company associated with the site of site_id
  • secret (string): Nectar signed secret used in the client-side iframe integration for magic links

What’s Next