Adaptricity Docs  beta

Appearance

API ​

We offer a couple of public REST endpoints that can be used to do 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.

Authentication ​

To access the endpoints, you need an API Token, that you can create in your user profile

Create token

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.

http
POST https://{instance-id}.adaptricity.com/api/grid/{grid-id}/calculatepowerflow/v2

Preparation ​

As a preparation, we first upload a grid into Adaptricity:

Grids > Grid Editor > Load grid from file > upload example-grid.xml

Upload grid

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:

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

http
POST https://{instance-id}.adaptricity.com/api/grid/{grid-id}/calculatepowerflow/v2

Request Headers ​

Set these request headers and replace {your-api-token} with your token.

http
X-Auth-Token: {your-api-token}
Content-Type: application/json

Request Body ​

The algorithm settings are passed in the body.

json
{
	"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:

bash
curl -X POST "https://adt-123456.adaptricity.com/api/grid/688109db1dadf237a782a8ef/calculatepowerflow/v2" \
  -H "X-Auth-Token: 68808f3f1dadf237a77ed9d7OMbL46g6QBJg6lAuUzbUoD1PGdtKoLriSAeqtsf_kr1Vdr5XAMFyB5ZTn-Eb85dy" \
  -H "Content-Type: application/json" \
  -d '{
    "DPGProtocolVersion": "2.0",
    "operationalVoltages": [],
    "algorithm": {
      "type": "FULL_NEWTON",
      "tolerance": 0.000001,
      "maxIter": 100
    }
  }'

Response ​

The response contains the power flow results including bus voltages, line currents, losses in the json format.

json
{
  "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
      }
    }
  ]
}