API energy data uploads

Our system exposes a dedicated API endpoint for users who require an automated way to push energy data to Fuel Switch. For general information about the API, including endpoints and documentation, see Fuel Switch API.

Prerequisites

The following is necessary to be in place before you get started with using the Fuel Switch API (the same follows for our sandbox environment). You must have:

1. KYC-approved account registered on Fuel Switch.

2. Approved renewable project

3. Meters registered to the project. If you aim to use the Fuel Switch API to upload meter data, you can select Manual as the meter type.

We recommend using our user interface for most of the setup, and limit API integration to data uploads.

Upload Data

There are several steps involved to upload energy data to Fuel Switch via the API. You can find the details on how to do this on our Swagger page.

The sections below give a high-level overview of the steps to go from authentication to uploading data and viewing the results, along with the mutations/queries to execute each action.

Authenticate

Authentication is done via API Keys. More details can be found on the Fuel Switch API page.

Upload Energy Data

We expose the addMeterData mutation for uploading energy data to a meter. This mutation expects the following parameters:

• meterId: The unique identifier of your meter. The section that follows explains how to retrieve this identifier. You can optionally save this on your application's side for regular use.

• file.name: We save every raw energy data upload as a unique file on our database. This parameter is for your convenience, to identify individual energy data uploads. Make sure it's unique to avoid confusion.

• blob64: A base64 encoded CSV string of the energy readings. For more information about the format of the CSV data, see Raw Format.

The snippet below shows how to convert CSV energy readings to a base64 string in a NodeJs application.

const { Buffer } = require('node:buffer');

const csv = 
"2024-03-25T11:30:05.563Z,141.60\n"+
"2024-03-25T12:00:05.563Z,144.00\n"+
"2024-03-25T12:30:05.563Z,194.00\n"+
"2024-03-25T13:00:05.563Z,200.00"

// Convert the CSV data to a base64-encoded string
const csvBase64 = Buffer.from(csv).toString("base64");

Note that energy data can be uploaded to our API at any frequency, as long as the interval between meter readings are greater than one second (as mentioned in Data Validation Checks).

Get Meter Details

To retrieve a list of meters linked to a specific project, and data relating to the meters, use the userRepMeters query. It expects a unique identifier for the project (the project ID) and pagination parameters to specify the number of meters to be retrieved. The section that follows shows how to get the project ID.

This mutation is useful for;

• Retrieving meter metadata details, such as the meter ID (used for uploading energy data), name and associated documents.

• Inspecting a summary of a meter's verified/unverified energy. The data returns are as follows:

  • verifiedEnergy: Verified energy is energy approved by the registry, and for which RECs have been issued.

  • unverifiedEnergy: Energy that has not yet been verified by the registry. This includes both data that has not been sent to the registry for approval, and data that is pending approval.

  • unverifiedStartDate: Epoch timestamp of the first (oldest) unverified energy reading.

  • unverifiedEndDate: Epoch timestamp of the last (most recent) unverified energy reading.

Get Project Details

Get a list of projects owned by your account, using the userReps query. This step is necessary to retrieve the project ID. You can consider storing this identifier in your application for future use.

Get Uploaded Energy Data

To retrieve uploaded energy data of a project, use the meterDataFiles query. It fetches a list of uploaded energy data files for a specific project. You can then filter the response to find all the uploads for a specific meter. This function is useful for finding the unique identifier for an erroneous upload, that you need to delete.

Delete Energy Data

To delete an energy data upload, use the deleteMeterUpload mutation. It expects a meter ID (retrieve using the userRepMeters query) and energy data file upload ID (retrieve using the meterDataFiles query).