API
We offer a couple of public REST endpoints that can be used to perform tasks like
- running calculations
- submitting connection requests
- exporting data from Adaptricity
Endpoint Documentation
All public endpoints are documented in Adaptricity under User > API Documentation.
Importing grids and time series is done through the separate Data Integration API (v3).
Authentication
To access the endpoints, you need an API Token, that you can create in your user profile
This token is your key into Adaptricity, treat it like a password!
Example
As an example we'll look at the power flow endpoint, that calculates the power flow of a grid and returns the power flow results in the json format.
POST https://{instance-id}.adaptricity.com/api/grid/{grid-id}/calculatepowerflow/v2Preparation
As a preparation, we first upload a grid into Adaptricity:
Grids > Grid Editor > Load grid from file > upload example-grid.xml
Each grid has a unique 24 character ID that can be found in the url (marked yellow in the screenshot). Extract the gridID from the URL. Be sure to exclude the leading ‘g’ when copying the ID, as it’s not part of the actual gridID.
The adaptricity web URLs usually have this format:
https://{instance-id}.adaptricity.com/#/{project-id}/s/g{grid-id}/URL
Take the endpoint URL and replace {grid-id} and {instance-id} with your IDs.
POST https://{instance-id}.adaptricity.com/api/grid/{grid-id}/calculatepowerflow/v2Request Headers
Set these request headers and replace {your-api-token} with your token.
X-Auth-Token: {your-api-token}
Content-Type: application/jsonRequest Body
The algorithm settings are passed in the body.
{
"DPGProtocolVersion": "2.0",
"operationalVoltages": [],
"algorithm": {
"type": "FULL_NEWTON",
"tolerance": 0.000001,
"maxIter": 1000
}
}Run request
Now you can send this request with a tool like Postman, or directly in the console with e.g. curl. This is an example of the full curl command:
curl -X POST "https://adt-123456.adaptricity.com/api/grid/688109db1dadf237a782a8ef/calculatepowerflow/v2" \
-H "X-Auth-Token: {your-api-token}" \
-H "Content-Type: application/json" \
-d '{
"DPGProtocolVersion": "2.0",
"operationalVoltages": [],
"algorithm": {
"type": "FULL_NEWTON",
"tolerance": 0.000001,
"maxIter": 1000
}
}'Response
The response contains the power flow results including bus voltages, line currents, losses in the json format.
{
"convergenceInfo": {
"algorithm": "Full Newton-Raphson",
"hasConverged": true,
"numIterations": 1,
"disabledWarmStart": false
},
"powerFlowSummary": {
"load": {
"total": { "activePowerInMegawatt": 0.01, "reactivePowerInMegavar": 0.0 },
"byVoltageLevel": {
"20.0 kV": {
"activePowerInMegawatt": 0.0,
"reactivePowerInMegavar": 0.0
},
"0.4 kV": {
"activePowerInMegawatt": 0.01,
"reactivePowerInMegavar": 0.0
}
}
},
"generation": {
"total": { "activePowerInMegawatt": 0.0, "reactivePowerInMegavar": 0.0 },
"byVoltageLevel": {
"20.0 kV": {
"activePowerInMegawatt": 0.0,
"reactivePowerInMegavar": 0.0
},
"0.4 kV": {
"activePowerInMegawatt": 0.0,
"reactivePowerInMegavar": 0.0
}
}
},
"flow": {
"total": {
"activePowerInMegawatt": 0.01998689567564519,
"reactivePowerInMegavar": -5.192047912955003e-6
},
"byVoltageLevel": {
"0.4 kV": {
"activePowerInMegawatt": 0.009988478786482116,
"reactivePowerInMegavar": 1.9374434934664843e-8
},
"20.0 / 0.4 kV": {
"activePowerInMegawatt": 0.009998416889163076,
"reactivePowerInMegavar": -5.211422347889668e-6
}
}
},
"losses": {
"total": {
"activePowerInMegawatt": 1.0498950978737875e-5,
"reactivePowerInMegavar": 9.72651577058059e-6
},
"byVoltageLevel": {
"0.4 kV": {
"activePowerInMegawatt": 9.435569420235268e-6,
"reactivePowerInMegavar": 2.6319084106551927e-6
},
"20.0 / 0.4 kV": {
"activePowerInMegawatt": 1.0633815585026074e-6,
"reactivePowerInMegavar": 7.094607359925398e-6
}
}
}
},
"powerFlowResult": [
{
"elementType": "bus",
"id": "bus_1",
"powerFlowData": {
"voltageInPerUnit": 1.0,
"angleInRadians": 0.0,
"activeBusLoadInMegawatt": 0.0,
"reactiveBusLoadInMegavar": 0.0,
"activeBusGenerationInMegawatt": 0.0,
"reactiveBusGenerationInMegavar": 0.0,
"voltageInKilovolt": 20.0,
"activeResidualBusLoadInMegawatt": 0.0,
"reactiveResidualBusLoadInMegavar": 0.0,
"angleInDegrees": 0.0
}
},
{
"elementType": "bus",
"id": "bus_2",
"powerFlowData": {
"voltageInPerUnit": 0.999893774408436,
"angleInRadians": -7.095529905871144e-4,
"activeBusLoadInMegawatt": 0.0,
"reactiveBusLoadInMegavar": 0.0,
"activeBusGenerationInMegawatt": 0.0,
"reactiveBusGenerationInMegavar": 0.0,
"voltageInKilovolt": 0.3999575097633744,
"activeResidualBusLoadInMegawatt": 0.0,
"reactiveResidualBusLoadInMegavar": 0.0,
"angleInDegrees": -0.04065439170152748
}
},
{
"elementType": "bus",
"id": "bus_3",
"powerFlowData": {
"voltageInPerUnit": 0.9989500624829588,
"angleInRadians": -0.0011471351227720045,
"activeBusLoadInMegawatt": 0.01,
"reactiveBusLoadInMegavar": 0.0,
"activeBusGenerationInMegawatt": 0.0,
"reactiveBusGenerationInMegavar": 0.0,
"voltageInKilovolt": 0.39958002499318357,
"activeResidualBusLoadInMegawatt": 0.01,
"reactiveResidualBusLoadInMegavar": 0.0,
"angleInDegrees": -0.06572600106605739
}
},
{
"elementType": "powerline",
"id": "powerline_1",
"powerFlowData": {
"activePowerInMegawatt": 0.009988478786482116,
"reactivePowerInMegavar": 1.9374434934664843e-8,
"activeLossInMegawatt": 9.435569420235268e-6,
"reactiveLossInMegavar": 2.6319084106551927e-6,
"apparentPowerInMegavoltampere": 0.009988478786500906,
"activePowerInPerUnit": 9.988478786482116e-5,
"reactivePowerInPerUnit": 1.9374434934664843e-10,
"activeLossInPerUnit": 9.435569420235268e-8,
"reactiveLossInPerUnit": 2.6319084106551927e-8,
"apparentPowerInPerUnit": 9.988478786500907e-5,
"loadingInPerUnit": 0.04008966745271987,
"currentInAmpere": 14.432280282979153,
"currentInPerUnit": 9.998977087677769e-5,
"currentAngleInRadians": -0.0011490748010613216,
"voltageDropInVolt": 0.37748477019086124,
"loadingInPercent": 4.008966745271987,
"activePowerFlowingToBus2": true,
"reactivePowerFlowingToBus2": true
}
},
{
"elementType": "transformer",
"id": "transformer_1",
"powerFlowData": {
"activePowerInMegawatt": 0.009998416889163076,
"reactivePowerInMegavar": -5.211422347889668e-6,
"activeLossInMegawatt": 1.0633815585026074e-6,
"reactiveLossInMegavar": 7.094607359925398e-6,
"apparentPowerInMegavoltampere": 0.009998418247324139,
"activePowerInPerUnit": 9.998416889163075e-5,
"reactivePowerInPerUnit": -5.211422347889668e-8,
"activeLossInPerUnit": 1.0633815585026074e-8,
"reactiveLossInPerUnit": 7.094607359925398e-8,
"apparentPowerInPerUnit": 9.998418247324139e-5,
"loadingInPerUnit": 0.01587050515448276,
"currentInAmpere": 14.433006821095084,
"currentInPerUnit": 9.99948044804994e-5,
"currentAngleInRadians": -1.8832828710316994e-4,
"voltageDropInVolt": 0.04249023662561413,
"loadingInPercent": 1.587050515448276,
"activePowerFlowingToBus2": true,
"reactivePowerFlowingToBus2": false
}
}
]
}