The data
Comparability
Two operators' “available capacity” are rarely the same quantity. The API makes that visible, and lets you choose how strict to be about it.
Why figures are not automatically comparable
- One operator studies the network intact, another with an outage.
- One subtracts reserved and pre-reserved capacity before publishing, another does not.
- One publishes firm capacity, another offers more under a curtailment band.
- One publishes MW, another MVA; one per substation, another per supply area.
Each methodology has a comparability_class. Records in the same class were computed in a way that makes side-by-side comparison meaningful; records in different classes were not, whatever their units say.
The three modes
| comparability= | Behaviour |
|---|---|
| best_effort | The default. Mixed classes are returned, and meta.warnings says so. |
| strict | Every matching record must share one class. If they do not, 422 capacity_semantics_not_comparable, with the classes found in details.classes. Nothing is returned rather than something misleading. |
| raw | Everything best_effort returns, plus records with unknown dimensions (a direction, type or technology the operator did not state). |
curl "https://api.gridcapacityapi.com/v1/capacity/search?direction=injection&technology=solar_pv&comparability=strict" \ -H "Authorization: Bearer gc_live_..."{
"error": {
"code": "capacity_semantics_not_comparable",
"message": "The requested sources cannot be compared under strict comparability mode.",
"request_id": "req_…",
"details": {
"classes": [
"…",
"…"
]
}
}
}Adding figures up
Where methodology.non_additive is true, figures must not be summed across assets: neighbouring substations share upstream constraints, and the capacity of two is not the sum of each. The API never sums them for you, and a total you compute yourself should say what it ignores.
Use strict for automated decisions
best_effort is right for exploring and for maps. When code ranks, filters or alerts on figures, use strict: an error you handle is better than a ranking that quietly mixes two definitions.