Upload consumption and production metering data

This article explains how to upload metering data (production and consumption volumes) into the Granular Energy platform. It covers the CSV format, the manual upload flow for testing, and why an automated API integration is strongly recommended for production use.

What is this about?

Once your portfolio structure is defined (customers, meters, and production devices) you can upload the generation and consumption data for each metering point.

There are two types of metering data:

  • Production metering data: the energy generated by each asset metering point in your supply portfolio
  • Consumption metering data: the energy consumed by each metering point in your demand portfolio

Both follow the same 3-column format and the same upload path. The data you provide represents the "best available" volumes at the time of upload: this can be forecasts initially, replaced by actuals as they become available.

The data format

The metering file is a 3-column CSV, the same for both production and consumption data:

Column Format Description
metering_point String Your internal reference for the meter must match exactly the metering_point_reference  used when defining the portfolio. Case-sensitive.
period_start ISO 8601 datetime with timezone Start of the measurement interval. Example: 2024-03-01T00:00:00+01:00
quantity Float Energy quantity in kWh, maximum 3 decimal places (Wh precision)

Supported granularities:

  • Sub-hourly: intervals of 5, 10, 15, or 30 minutes
  • Hourly: 60-minute intervals
  • Monthly: one row per month, timestamped at the first of the month at 00:00:00+zz:zz

A single file can contain data for multiple metering points and multiple time periods. All rows in a given file must use the same granularity as the platform infers this automatically and validates it on upload.

How to manually upload CSVs via the platform UI

The manual CSV upload is the best approach for initial testing, onboarding validation, and one-off corrections. For ongoing production use, refer to the API section below.

  • In the platform, navigate to Import data (under Portfolio in the left sidebar)
  • Select either "Consumption metering data" or "Production metering data" depending on what you are uploading

Import data navigation


  • Drag-and-drop your CSV file in the upload area, or select it from your file browser
  • Click "Continue". The platform will validate your file and surface any errors at the top of the screen.
  • In case of format errors, the platform will point you towards the error.

Upload confirmation screen

  • Once processing is complete, the uploaded volumes will be reflected in your dashboards and available for allocation.

API for production environments

The manual CSV upload are suited to testing and initial data loading, but it is not designed as a recurring workflow. For live portfolios, an automated API integration is strongly recommended as the most robust solution for data flows. See our API documentation and guides HERE (LINK).

The key reasons:

  • Accuracy: at scale, manual uploads are error-prone. An automated feed eliminates transcription mistakes and format inconsistencies.
  • Timeliness: allocation quality depends on up-to-date data. With an API integration, metering data can be refreshed automatically as new readings become available (daily, hourly, or near real-time). This will ensure your positions and dashboards reflect the latest picture.
  • Auditability: automated pipelines create a consistent, traceable data history. Manual uploads can introduce gaps or overlaps that are harder to diagnose later.
  • Scale: portfolios with hundreds or thousands of metering points quickly become impractical to manage via CSV. The API handles this transparently.

In practice, Granular Energy's team will work with you during onboarding to set up an ETL pipeline or direct API integration, connecting your internal systems (MDMS, billing, ERP) to the platform's data endpoints. For most clients, this removes the need for manual uploads entirely once the integration is live.

API endpoints:

  • Production metering: POST <https://data-api.granular-energy.com/portfolio/generation/upload >
  • Consumption metering: POST <https://data-api.granular-energy.com/portfolio/demand-metering/upload >

Authentication uses a Bearer token (Authorization: Bearer {your_api_key} ). After uploading, poll the status endpoint with the returned file_id  to confirm processing. Full API documentation, including request parameters and Python examples, are available in the Platform under Support → API-Documentation on the bottom left.

Tips & things to know

  • Metering point references must match exactly. The metering_point  value in your data file must be identical (including case) to the metering_point_reference  you used when defining the portfolio. A mismatch will cause the upload to fail or the data to be silently unassociated.
  • Re-uploads overwrite existing data at matching granularity. If you re-upload data for a meter and time period that already exists, it will replace the previous values, as long as the granularity matches. If the granularity differs from what was previously uploaded for that meter, you will need to contact support@granular-energy.com for guidance.
  • Forecasts before actuals is fine. The platform treats every upload as the "best available" data at the time. You can upload forecasted consumption or production early to enable allocation planning, then replace it with actuals once available.
  • Monthly data has a specific timestamp convention. For monthly granularity, each row's period_start  must be the first of the month at midnight with timezone offset — e.g. 2024-01-01T00:00:00+01:00 . Any other timestamp within the month will cause a validation error.
  • Be mindful of daylight savings time transitions when preparing consumption data. The platform stores timestamps based on location, so it is preferable to submit data with timestamps already converted to UTC in ISO 8601 format to avoid any ambiguity.
  • For questions or support, contact support@granular-energy.com