Analytics & Monitoring API — Energy and Revenue

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).

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.

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"
}

​Authentication

​Common query parameters

​Energy analytics

​Energy by charge point

​Energy by project

​Energy by time of day

​Energy trends

​Revenue analytics

​Revenue summary

​Revenue by charge point

​Revenue by tariff

​Revenue forecasts

​Issues and alerts

​List operational issues

​Issues summary

​Acknowledge an issue

​Fleet health score

​API usage

​Usage today

​API usage trends

​Live status and monitoring

​Live charge point status

​Connection health

​Heartbeat status

​Project status overview

Authentication

Common query parameters

Energy analytics

Energy by charge point

Energy by project

Energy by time of day

Energy trends

Revenue analytics

Revenue summary

Revenue by charge point

Revenue by tariff

Revenue forecasts

Issues and alerts

List operational issues

Issues summary

Acknowledge an issue

Fleet health score

API usage

Usage today

API usage trends

Live status and monitoring

Live charge point status

Connection health

Heartbeat status

Project status overview