Reporting and dashboards

By the end of this playbook you’ll know which Spirii data to pull, and how to pull it reliably, to power reporting your own way — a live operations cockpit, an automated month-end report, or a tailored financial export.

​

Before you start

This playbook is for operators and e-mobility providers who need reporting beyond what Connect offers out of the box. Connect already gives you a business overview, live operational dashboards, and CDR exports; reach for the API when you need custom KPIs, your own storage, or feeds into other systems. You’ll need an API key and a working understanding of sessions and CDRs, which are the backbone of most reports.

​

What you can build

• A live operations cockpit showing connector availability and faults across your network.
• An automated business report — daily or monthly usage, revenue, and utilisation, sent to your operations or management team.
• A financial export shaped for your accounting system, reconciling sessions, payments, and VAT.
• A performance dashboard to spot utilisation trends and margin opportunities.

​

The data you’ll use

Four resources cover almost every reporting need. Follow the component link for what each represents; use the reference for the full schema and every field.

​

What a CDR gives you

A single CDR carries most of what a report needs, so you rarely have to stitch resources together:

• Energy and time — consumed (kWh), duration (charging, idle, total), startedAt / endedAt, highestPowerDrawn.
• Money — price (amount, amountExVat, currency, vatRate), and cpoDefaultPrice (the price before vouchers and discounts, useful for margin analysis).
• Pricing — price.tariffId and tariffName are embedded, so you can attribute revenue to a tariff without a second call.
• Who and how — auth (method and token), paymentMethod, paymentStatus, and voucher where one applied.
• Where — location (name, city, country, type), evseId, chargeBoxId.
• Roaming — isRoaming and roamingDetails to separate roaming sessions from your own network.

Some token and customer fields are personal data and are only returned with sufficient access. Use the fields parameter to request only the properties your report needs and keep payloads small.

​

Integration patterns

​

Live operations cockpit

1. Poll Locations on a short interval for current EVSE and connector status, scoping the request to the sites you care about.
2. Poll Transactions for sessions in progress, using its updatedAt filter to fetch only what changed since your last pull.
3. Surface current availability and faults, and flag anything stuck.

​

Nightly report

1. Query CDRs for the day’s completed sessions with the updatedAtFrom and updatedAtTo window:
   curl "https://api.spirii.com/v2/charge-records?updatedAtFrom=2025-01-27T00:00:00.000Z&updatedAtTo=2025-01-28T00:00:00.000Z&limit=5000" \
     -H "Authorization: Bearer <SPIRII_API_KEY>"
   
2. Store the records locally, then compile and send the day’s usage and revenue summary.

​

Monthly report

1. Aggregate the CDRs you’ve stored over the month rather than refetching them.
2. Group by location, tariff, or payment method to build the figures management needs — most of what you need is already on each CDR.
3. For advanced slicing, the CDR endpoint accepts a filter parameter (a JSON query) so you can, for example, return only the sessions at a set of locations:
   /v2/charge-records?filter={"location.id":{"$in":[12345,67890]}}
   

​

Best practices

• Sync incrementally. Pull only what changed using each endpoint’s time filter rather than refetching everything. The parameter names differ by endpoint — CDRs use updatedAtFrom / updatedAtTo, transactions use updatedAt — so confirm each on the reference. See Filtering.
• Page through completely. List endpoints return results in pages; follow the cursor to the end, and set limit explicitly rather than relying on defaults. See Pagination.
• Store CDRs locally. Keep a copy of completed records to cut repeat calls and stay clear of the rate limit.
• Retry safely. Back off and retry on transient errors; don’t retry a rejected request unchanged. See Errors.
• Map identifiers across systems. Align on location.id and evseId when joining Spirii data with your own, to keep records consistent and catch duplicates. See Identifiers.

​

Next steps