Charger Health

GET /api/charger-health

Retrieve health, uptime, error, and utilization statistics for all chargers in an organization, grouped by charger and port, over a specified time interval. This endpoint is useful for generating reliability and performance reports for your charging infrastructure.

Parameters

Parameters should be passed as query parameters on the URL.

• startTimestamp (optional) - ISO 8601 date string. Start of the interval to analyze. Defaults to 30 days before the current time if not provided.

• endTimestamp (optional) - ISO 8601 date string. End of the interval to analyze. Defaults to the current time if not provided. If a future date is provided, it will be capped at the current time.

• siteIds (optional) - Array of site IDs to filter for. To pass multiple site IDs, add them to the query parameters like this: siteIds[]=101&siteIds[]=102.

• chargerIds (optional) - Array of charger IDs to filter for. To pass multiple charger IDs, add them to the query parameters like this: chargerIds[]=201&chargerIds[]=202.

Response

The JSON response contains a summary field with aggregate statistics for the interval, and a data field with per-charger and per-port statistics.

A few notes:

• activeTimeInIntervalSeconds may be less than the total interval if the charger was activated after the start of the interval -- for example, if you select the month of June but the charger first came online on June 15, all of the statistics will be based on the second half of the month (instead of starting out immediately for 50% downtime).

• Error counts are grouped by type: endedEarly (charging stopped before expected), failedToStart (charging could not begin), and other (miscellaneous or unknown errors).

• The uptime seconds for a charger are the sum of the uptime across the ports, so the uptime can be longer than the actual length of the interval. As an example, if you select 2 weeks of data for a 2-port charger, the total uptime could be 4 weeks if both ports were up the whole time.

{
  summary: {
    startTime: string; // ISO 8601 format
    endTime: string; // ISO 8601 format
    errorCounts: {
      endedEarly: number;
      failedToStart: number;
      other: number;
      total: number;
    }
    chargingSessionsCount: number;
  }
  data: {
    chargerId: number;
    serialNumber: string;
    name: string;
    activeTimeInIntervalSeconds: number; // May be less than the interval if charger was activated after start
    site: {
      id: number;
      name: string;
    }
    connectivity: {
      onlineSeconds: number;
      offlineSeconds: number;
      onlinePercent: number;
    }
    maintenance: {
      maintenanceSeconds: number;
      maintenancePercent: number;
    }
    uptime: {
      faultedSeconds: number;
      availableSeconds: number;
      unavailableSeconds: number;
      uptimePercent: number;
    }
    utilization: {
      chargingSessionSeconds: number;
      utilizationPercent: number;
    }
    errorCounts: {
      endedEarly: number;
      failedToStart: number;
      other: number;
      total: number;
    }
    chargingSessionsCount: number;
    ports: {
      id: number;
      name: string;
      uptime: {
        faultedSeconds: number;
        availableSeconds: number;
        unavailableSeconds: number;
        uptimePercent: number;
      }
      utilization: {
        chargingSessionSeconds: number;
        utilizationPercent: number;
      }
      errorCounts: {
        endedEarly: number;
        failedToStart: number;
        other: number;
        total: number;
      }
      chargingSessionsCount: number;
    }
    [];
  }
  [];
}

Example request and response

Request:

curl "https://api.getflipturn.com/api/charger-health?startTimestamp=2024-07-01T00:00:00.000Z&endTimestamp=2024-07-31T23:59:59.999Z" -H "Authorization: Bearer {token}"

Response:

{
  "summary": {
    "startTime": "2024-07-01T00:00:00.000Z",
    "endTime": "2024-07-31T23:59:59.999Z",
    "errorCounts": {
      "endedEarly": 2,
      "failedToStart": 1,
      "other": 0,
      "total": 3
    },
    "chargingSessionsCount": 42
  },
  "data": [
    {
      "chargerId": 101,
      "serialNumber": "FT-CHARGER-0001",
      "name": "Main Charger",
      "activeTimeInIntervalSeconds": 2678400,
      "site": {
        "id": 1,
        "name": "Site 1"
      },
      "connectivity": {
        "onlineSeconds": 2600000,
        "offlineSeconds": 78400,
        "onlinePercent": 97.1
      },
      "maintenance": {
        "maintenanceSeconds": 3600,
        "maintenancePercent": 0.13
      },
      "uptime": {
        "faultedSeconds": 1200,
        "availableSeconds": 2590000,
        "unavailableSeconds": 8000,
        "uptimePercent": 99.6
      },
      "utilization": {
        "chargingSessionSeconds": 120000,
        "utilizationPercent": 4.6
      },
      "errorCounts": {
        "endedEarly": 1,
        "failedToStart": 1,
        "other": 0,
        "total": 2
      },
      "chargingSessionsCount": 20,
      "ports": [
        {
          "id": 201,
          "name": "Port 1",
          "uptime": {
            "faultedSeconds": 600,
            "availableSeconds": 1295000,
            "unavailableSeconds": 4000,
            "uptimePercent": 99.7
          },
          "utilization": {
            "chargingSessionSeconds": 60000,
            "utilizationPercent": 4.6
          },
          "errorCounts": {
            "endedEarly": 1,
            "failedToStart": 0,
            "other": 0,
            "total": 1
          },
          "chargingSessionsCount": 10
        }
      ]
    }
  ]
}