# Quality Metrics

> A data-driven view of how reliably each charge point performs.

Quality data is computed from real session history, success rates, latency, silent sessions, and more, and distilled into a single **score** plus a human-readable **reliability** label.

Quality data is returned on each charge point when you fetch a location with `enrich_charge_points=true`. If a charge point has no recorded sessions yet, quality data is not available. The full `quality` object is in the [reference](/docs/charge-now/reference/chargenow-api/location).

## What quality data includes

| Field                        | What it is                                                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `score`                      | Composite quality score, `0` (worst) to `100` (best).                                                         |
| `reliability`                | Human-readable label for the score: `excellent`, `good`, `fair`, `poor`, `very_poor`, or `insufficient_data`. |
| `total_sessions`             | Number of sessions the metrics are computed from.                                                             |
| `success_rate`               | Proportion of sessions that completed successfully.                                                           |
| `silent_session_rate`        | Proportion where the charge point never confirmed it had started.                                             |
| `avg_start_latency_sec`      | How quickly the charge point confirms charging has started.                                                   |
| `avg_settlement_latency_sec` | How quickly it confirms the final cost after stopping.                                                        |

## Understanding the reliability label

The **reliability** label maps the numeric `score` to a tier that's easy to display in a UI or use in business logic. A minimum of **5 sessions** is required before a meaningful label is assigned.

| Label               | Score range | What it means                                                       |
| ------------------- | ----------- | ------------------------------------------------------------------- |
| `excellent`         | 80–100      | Consistently successful sessions with low latency                   |
| `good`              | 60–79       | Reliable overall with occasional issues                             |
| `fair`              | 40–59       | Noticeable problems, drivers may experience delays or failures      |
| `poor`              | 20–39       | Frequent issues, consider warning users before they start a session |
| `very_poor`         | 0–19        | Serious reliability problems, sessions regularly fail or stall      |
| `insufficient_data` | n/a         | Fewer than 5 sessions recorded; not enough history to judge         |

## Understanding individual metrics

### score

A composite quality score from **0** to **100** that summarises overall charge point health. It blends five weighted components:

| Component                     | Weight | What it measures                                                                         |
| ----------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| Session success rate          | 35%    | Proportion of sessions that reach `Settled`                                              |
| Start failure rate (inverse)  | 25%    | Proportion of sessions that do *not* fail before reaching `Started`                      |
| Silent session rate (inverse) | 15%    | Proportion of settled sessions where the charge point *did* communicate `Started` status |
| Start latency                 | 15%    | How quickly the charge point responds after session creation                             |
| Settlement latency            | 10%    | How quickly the charge point settles after stopping                                      |

When a component has no data (e.g. no sessions have reached `Started` yet), its weight is redistributed proportionally among the remaining components. Charge points with fewer than 5 sessions receive a neutral score of **50** and a reliability label of `insufficient_data`.

### success\_rate

The ratio of **settled** sessions to **total** terminal sessions (0.0–1.0). A settled session completed the full charging cycle and reached the `Settled` billing state.

| Value         | Reading                                                                |
| ------------- | ---------------------------------------------------------------------- |
| `0.95`+       | Excellent; almost every session completes                              |
| `0.80`–`0.94` | Good; occasional failures                                              |
| Below `0.80`  | Investigate; the charge point may have hardware or connectivity issues |

### silent\_session\_rate

The ratio of settled sessions where the charge point **never communicated `Started` status** back to the system (0.0–1.0). A silent session does not mean the car wasn't charging: the charge point may well have been delivering energy but failed to report the `Started` state. The session still settles because the CPO confirms billing independently.

| Value         | Reading                                                          |
| ------------- | ---------------------------------------------------------------- |
| Below `0.05`  | Normal; most charge points have a few silent sessions            |
| `0.05`–`0.15` | Elevated; likely communication or reporting delays               |
| Above `0.15`  | High; the charge point regularly fails to report charging status |

A high silent session rate degrades the driver experience: without a `Started` confirmation the app can't show live progress, even though the vehicle is likely charging, which causes confusion and support requests.

### avg\_start\_latency\_sec

Average seconds between session creation (`Pending`) and the charge point confirming energy delivery (`Started`). `null` when no session has ever reached `Started`.

| Value     | Reading                                                 |
| --------- | ------------------------------------------------------- |
| Under 15s | Fast; typical for well-connected charge points          |
| 15–45s    | Normal                                                  |
| Over 45s  | Slow; the charge point or CPO backend may be under load |

The charge point may already be delivering energy but be slow to report `Started`, so a driver is left waiting without confirmation in the app.

### avg\_settlement\_latency\_sec

Average seconds between the session stopping (`Stopped`) and final billing confirmation (`Settled`). `null` when there is no settlement-latency data. Values are typically in the hundreds to thousands of seconds because settlement depends on CPO billing systems.

| Value                    | Reading                                     |
| ------------------------ | ------------------------------------------- |
| Under 300s (5 min)       | Fast settlement                             |
| 300–3600s (5 min – 1 hr) | Normal                                      |
| Over 3600s (1 hr+)       | Slow; the CPO may batch-process settlements |

High settlement latency means drivers see a pending charge for longer, and you may need to hold a pre-authorisation amount for an extended period.

## Integration ideas

### Display a reliability badge

Map the `reliability` label to a colour and icon in your UI so drivers can judge charge point quality at a glance. For example, `excellent` green, `fair` yellow, `very_poor` red, and a neutral grey for `insufficient_data`.

### Adjust pre-authorisation amount

When `avg_settlement_latency_sec` is high, the final billing amount may arrive much later than expected. Consider increasing the pre-authorisation hold proportionally to cover delayed billing.

### Show driver warnings

When `reliability` is `poor` or `very_poor`, surface a warning so the driver can pick a better charge point. For a high `silent_session_rate`, tell drivers the charge point may not report live status: their vehicle is likely charging even if the app can't confirm it.

### Sort or filter charge points by quality

Use `score` to rank nearby charge points so the best options appear first, or filter out charge points below a minimum score to avoid showing unreliable options.

### Monitor fleet charge points

If you manage a fleet, poll quality metrics periodically and alert when a previously reliable charge point degrades, for example when `score` drops below a threshold or `success_rate` falls significantly.

### Handle insufficient data

When `reliability` is `insufficient_data`, the charge point has fewer than 5 recorded sessions. Show a neutral state (e.g. "New") rather than hiding the charge point or showing a negative indicator.