Analytics & Monitoring API — Energy and Revenue

Query energy consumption, revenue, fleet health, and operational issues across your charging network with flexible date ranges and groupings.

The analytics endpoints give you quantitative insight into your charging network — how much energy you have delivered, what revenue you have generated, where issues are occurring, and how healthy your fleet is overall. All analytics endpoints return aggregated data; for raw session records use the Sessions API.

Authentication

Authorization: Bearer YOUR_API_KEY
# or
X-API-Key: YOUR_API_KEY

Common query parameters

Most analytics endpoints accept these query parameters to control the scope and granularity of results.

from · string

Start of the reporting period in ISO 8601 format (e.g., 2024-01-01).

to · string

End of the reporting period in ISO 8601 format (e.g., 2024-01-31).

charge_point_id · string

Restrict results to a single charge point.

project_id · string

Restrict results to a single project (site).

granularity · string · default: "day"

Time bucket size for trend endpoints: day, week, or month.

---

Energy analytics

Energy by charge point

GET /api/v1/analytics/energy/by-charge-point

Returns total energy delivered in kWh for each charge point over the specified period.

curl "https://api.dynamo-csms.com/api/v1/analytics/energy/by-charge-point?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "data": [
    {
      "charge_point_id": "cp_001",
      "charge_point_name": "Canary Wharf — Bay 1",
      "energy_kwh": 1842.6,
      "session_count": 214
    },
    {
      "charge_point_id": "cp_002",
      "charge_point_name": "Canary Wharf — Bay 2",
      "energy_kwh": 1603.1,
      "session_count": 187
    }
  ],
  "total_energy_kwh": 3445.7,
  "total_sessions": 401
}

Energy by project

GET /api/v1/analytics/energy/by-project

Returns total energy delivered grouped by project (site). Useful for comparing performance across locations.

curl "https://api.dynamo-csms.com/api/v1/analytics/energy/by-project?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "data": [
    {
      "project_id": "proj_01HXD6E5F4G3H2I1",
      "project_name": "Canary Wharf Car Park",
      "energy_kwh": 12480.3,
      "session_count": 1402
    }
  ]
}

Energy by time of day

GET /api/v1/analytics/energy/by-time-of-day

Returns average energy delivered per hour of the day (0–23). Use this to understand peak demand patterns and inform load management.

curl "https://api.dynamo-csms.com/api/v1/analytics/energy/by-time-of-day?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "data": [
    { "hour": 0, "avg_energy_kwh": 12.3 },
    { "hour": 7, "avg_energy_kwh": 48.9 },
    { "hour": 8, "avg_energy_kwh": 91.2 },
    { "hour": 9, "avg_energy_kwh": 87.5 },
    { "hour": 17, "avg_energy_kwh": 103.7 },
    { "hour": 18, "avg_energy_kwh": 96.4 }
  ]
}

Energy trends

GET /api/v1/analytics/energy/trends

Returns energy delivered over time, bucketed by the granularity parameter. Suitable for rendering time-series charts.

curl "https://api.dynamo-csms.com/api/v1/analytics/energy/trends?from=2024-01-01&to=2024-03-31&granularity=week" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "from": "2024-01-01",
  "to": "2024-03-31",
  "granularity": "week",
  "data": [
    { "period": "2024-01-01", "energy_kwh": 8421.0, "session_count": 962 },
    { "period": "2024-01-08", "energy_kwh": 9103.4, "session_count": 1044 },
    { "period": "2024-01-15", "energy_kwh": 8872.1, "session_count": 1011 }
  ]
}

---

Revenue analytics

Revenue summary

GET /api/v1/analytics/revenue/summary

Returns aggregate revenue figures for the specified period.

curl "https://api.dynamo-csms.com/api/v1/analytics/revenue/summary?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "currency": "GBP",
  "total_revenue": 14302.50,
  "avg_revenue_per_session": 10.22,
  "session_count": 1400,
  "avg_session_duration_minutes": 68
}

total_revenue · number

Total revenue collected in the reporting period (in the organization’s base currency).

avg_revenue_per_session · number

Mean revenue per completed session.

session_count · number

Number of completed sessions in the period.

Revenue by charge point

GET /api/v1/analytics/revenue/by-charge-point

Returns revenue broken down per charge point, useful for identifying your highest- and lowest-performing assets.

Revenue by tariff

GET /api/v1/analytics/revenue/by-tariff

Returns revenue grouped by tariff, showing which pricing plans are driving the most income.

curl "https://api.dynamo-csms.com/api/v1/analytics/revenue/by-tariff?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "tariff_id": "tar_01HXH0I9J8K7L6M5",
      "tariff_name": "Peak Rate",
      "revenue": 8940.00,
      "session_count": 820
    },
    {
      "tariff_id": "tar_01HXH0I9J8K7L6M6",
      "tariff_name": "Off-Peak",
      "revenue": 5362.50,
      "session_count": 580
    }
  ]
}

Revenue forecasts

GET /api/v1/analytics/revenue/forecasts

Returns a revenue forecast for the next 30, 60, and 90 days based on historical trends and current utilization.

curl https://api.dynamo-csms.com/api/v1/analytics/revenue/forecasts \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "generated_at": "2024-01-20T10:00:00Z",
  "forecasts": [
    { "horizon_days": 30, "forecast_revenue": 15100.00, "confidence_low": 13800.00, "confidence_high": 16400.00 },
    { "horizon_days": 60, "forecast_revenue": 30400.00, "confidence_low": 27200.00, "confidence_high": 33600.00 },
    { "horizon_days": 90, "forecast_revenue": 46200.00, "confidence_low": 40900.00, "confidence_high": 51500.00 }
  ]
}

---

Issues and alerts

List operational issues

GET /api/v1/analytics/issues

Returns a list of active and recently resolved operational issues across your fleet.

status · string

Filter by issue status: open, acknowledged, or resolved.

type · string

Filter by issue type: connectivity, faulted, billing, firmware.

curl "https://api.dynamo-csms.com/api/v1/analytics/issues?status=open" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "issue_id": "iss_01HXI1J0K9L8M7N6",
      "type": "connectivity",
      "charge_point_id": "cp_005",
      "description": "Charge point has been offline for 4 hours",
      "severity": "high",
      "status": "open",
      "created_at": "2024-01-20T06:15:00Z"
    }
  ],
  "total": 1
}

Issues summary

GET /api/v1/analytics/issues/summary

Returns issue counts grouped by type and severity. Use this for dashboard-level health indicators.

curl https://api.dynamo-csms.com/api/v1/analytics/issues/summary \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "open_count": 3,
  "acknowledged_count": 1,
  "by_type": {
    "connectivity": 2,
    "faulted": 1,
    "billing": 1
  },
  "by_severity": {
    "critical": 0,
    "high": 2,
    "medium": 2
  }
}

Acknowledge an issue

POST /api/v1/analytics/issues/{issue_id}/acknowledge

Mark an issue as acknowledged to indicate that your team is aware of it and working on a resolution.

issue_id · string · required

The ID of the issue to acknowledge.

note · string

Optional note to record alongside the acknowledgement (e.g., “Field engineer dispatched”).

curl -X POST https://api.dynamo-csms.com/api/v1/analytics/issues/iss_01HXI1J0K9L8M7N6/acknowledge \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Field engineer dispatched, ETA 2 hours."}'

---

Fleet health score

GET /api/v1/analytics/health-score

Returns a single 0–100 score representing the overall health of your fleet, plus a breakdown by contributing factor. A score above 80 is considered healthy; below 60 indicates significant issues requiring attention.

curl https://api.dynamo-csms.com/api/v1/analytics/health-score \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "score": 87,
  "calculated_at": "2024-01-20T14:00:00Z",
  "breakdown": {
    "connectivity": 92,
    "uptime": 89,
    "session_success_rate": 94,
    "firmware_compliance": 81,
    "billing_accuracy": 96
  },
  "charge_points_total": 48,
  "charge_points_online": 45,
  "charge_points_faulted": 2
}

score · number

Overall fleet health score from 0 (critical) to 100 (perfect).

breakdown · object

Per-dimension scores contributing to the overall health score.

Show properties

connectivity · number

Score based on charger online/offline ratio.

uptime · number

Score based on availability over the past 30 days.

session_success_rate · number

Score based on the ratio of successfully completed sessions.

firmware_compliance · number

Score based on how many charge points are running the latest approved firmware.

billing_accuracy · number

Score based on dispute and error rates.

---

API usage

Usage today

GET /api/v1/analytics/usage/today

Returns a summary of your API request counts for the current calendar day, including rate limit consumption.

curl https://api.dynamo-csms.com/api/v1/analytics/usage/today \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "date": "2024-01-20",
  "requests_today": 4821,
  "rate_limit": 100000,
  "remaining": 95179,
  "top_endpoints": [
    { "endpoint": "GET /api/v1/charge-points", "count": 1203 },
    { "endpoint": "GET /api/v1/sessions", "count": 987 }
  ]
}

API usage trends

GET /api/v1/analytics/usage/analytics

Returns your API usage over time, bucketed by day. Useful for capacity planning and cost monitoring.

from · string

Start of the reporting period.

to · string

End of the reporting period.

curl "https://api.dynamo-csms.com/api/v1/analytics/usage/analytics?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "data": [
    { "date": "2024-01-01", "requests": 3204 },
    { "date": "2024-01-02", "requests": 4891 },
    { "date": "2024-01-03", "requests": 5120 }
  ],
  "total_requests": 142830
}

---

Live status and monitoring

These endpoints return real-time status for individual charge points and projects, complementing the historical analytics above.

Live charge point status

GET /api/v1/status/charge-points/{charge_point_id}/live-status

charge_point_id · string · required

The charge point ID.

curl https://api.dynamo-csms.com/api/v1/status/charge-points/cp_001/live-status \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "charge_point_id": "cp_001",
  "online": true,
  "connectors": [
    {
      "connector_id": 1,
      "status": "Charging",
      "session_id": "sess_01HXE7F6G5H4I3J2",
      "energy_kwh": 14.3,
      "power_kw": 7.4
    },
    {
      "connector_id": 2,
      "status": "Available",
      "session_id": null,
      "energy_kwh": null,
      "power_kw": null
    }
  ]
}

Connection health

GET /api/v1/status/charge-points/{charge_point_id}/connection-health

Returns WebSocket connection stability metrics for a charge point over the past 24 hours.

charge_point_id · string · required

The charge point ID.

curl https://api.dynamo-csms.com/api/v1/status/charge-points/cp_001/connection-health \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "charge_point_id": "cp_001",
  "uptime_percent_24h": 99.2,
  "disconnection_count_24h": 2,
  "last_connected_at": "2024-01-20T14:00:00Z",
  "last_disconnected_at": "2024-01-20T09:31:00Z"
}

Heartbeat status

GET /api/v1/status/charge-points/{charge_point_id}/heartbeat-status

Returns the timestamp and interval of the most recent OCPP heartbeat received from a charge point.

charge_point_id · string · required

The charge point ID.

{
  "charge_point_id": "cp_001",
  "last_heartbeat_at": "2024-01-20T14:29:45Z",
  "heartbeat_interval_seconds": 300,
  "status": "healthy"
}

Project status overview

GET /api/v1/status/projects/{project_id}/status-overview

Returns a rollup of connector statuses across all charge points in a project.

project_id · string · required

The project ID.

curl https://api.dynamo-csms.com/api/v1/status/projects/proj_01HXD6E5F4G3H2I1/status-overview \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "project_id": "proj_01HXD6E5F4G3H2I1",
  "project_name": "Canary Wharf Car Park",
  "charge_points_total": 12,
  "charge_points_online": 11,
  "connectors": {
    "available": 14,
    "charging": 7,
    "faulted": 1,
    "unavailable": 0
  },
  "updated_at": "2024-01-20T14:30:00Z"
}