Adaptricity Docs  beta

Appearance

Data integration API (v3) ​

Documentation of public REST-Api to import grid and time series data from an external system (like IDC, or an ETL system) into Adaptricity.

Endpoint grids ​

Provides a list of available xml file-IDs. For each Adaptricity Project, one grid-ID can be selected.

Change compared to v2 ​

  • removed unnecessary fields
  • using human readible ISO_8601 time stamps in response (instead of UNIX epoch milliseconds)

Example ​

GET https://your.domain.com/adaptricity/grids returns:

json
{
  "DPGProtocolVersion": "3.0",
  "grids": [
    {
      "gridID": "lv-and-mv",
      "description": null,
      "timestamp": "2023-09-30T14:30:00Z"
    }
  ]
}

Endpoint grid ​

Returns grid xml file for a specific file-ID. This file is imported by adaptricity and split at all transformers.

Change compared to v2 ​

  • none

Example ​

GET https://your.domain.com/adaptricity/grid/lv-and-mv returns:

xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GRID DPGXMLVersion="2.58">
    <BUSBAR_NODE>
        <Node x="-2.75" y="-47.25" Width="20.0" BaseVoltageInKilovolt="11.0" Type="Other" IsVertical="false" ID="bus_1" Name="">
            <GIS ShapeType="Point">
                <Points>
                    <Point Lat="46.98848496732053" Lon="9.635973472749184"/>
                </Points>
            </GIS>
        </Node>
        <Node x="-2.75" y="-15.875" Width="20.0" BaseVoltageInKilovolt="0.4" Type="Other" IsVertical="false" ID="bus_2" Name="">
            <GIS ShapeType="Point">
                <Points>
                    <Point Lat="46.98816059608366" Lon="9.635887615896436"/>
                </Points>
            </GIS>
        </Node>
        <Node x="-1.75" y="37.875" Width="20.0" BaseVoltageInKilovolt="0.4" Type="Virtual" IsVertical="false" ID="bus_3" Name="">
            <GIS ShapeType="Point">
                <Points>
                    <Point Lat="46.987980388990366" Lon="9.636118768961525"/>
                </Points>
            </GIS>
        </Node>
        <Node x="-2.0" y="56.0" Width="20.0" BaseVoltageInKilovolt="0.4" Type="SmallConnectionPoint" IsVertical="false" ID="bus_4" Name="">
            <GIS ShapeType="Point">
                <Points>
                    <Point Lat="46.98782721248338" Lon="9.636191417067694"/>
                </Points>
            </GIS>
        </Node>
    </BUSBAR_NODE>
    <LINE>
        <Line ResistanceInOhmPerKilometer="0.071" ReactanceInOhmPerKilometer="0.137" LengthInKilometer="0.02662" MaximumCurrentInAmpere="608.0" ShuntCapacitanceInMicrofaradPerKilometer="0.0" LibraryComponentName="BF GG-B2-1E 1x300 mm2 60°C (Luft, Ebene)" LibraryComponentType="BF GG-B2-1E" IsOverhead="false" CrossSection="1x300" Manufacturer="LEONI" Bus1ID="bus_2" Bus2ID="bus_3" ConnectedAtBus1="true" ConnectedAtBus2="true" ID="line_1">
            <GIS ShapeType="Line">
                <Points>
                    <Point Lat="46.98816059608366" Lon="9.635887615896436"/>
                    <Point Lat="46.987980388990366" Lon="9.636118768961525"/>
                </Points>
            </GIS>
        </Line>
    </LINE>
    <CONNECTION>
        <Connection ResistanceInMilliOhm="0.01" ReactanceInMilliOhm="0.0" Bus1ID="bus_3" Bus2ID="bus_4" ConnectedAtBus1="true" ConnectedAtBus2="true" ID="connection_1">
            <GIS ShapeType="Line">
                <Points>
                    <Point Lat="46.987980388990366" Lon="9.636118768961525"/>
                    <Point Lat="46.98782721248338" Lon="9.636191417067694"/>
                </Points>
            </GIS>
        </Connection>
    </CONNECTION>
    <LOAD>
        <Load Bus1ID="bus_4" ActiveLoadInMegawatt="0.05" LoadCategory="Other" Connected="true" ID="load_1">
            <ReactivePower Type="FIXED_Q" FixedReactivePowerInKilovoltampere="0.0"/>
        </Load>
    </LOAD>
    <GENERATOR/>
    <STORAGE/>
    <TRANSFORMER>
        <Transformer TransformerRatingInMegavoltampere="1.0" MaximumApparentPowerInMegavoltampere="1.0" ShortCircuitVoltageInPercent="5.0" CopperLossesInPercent="0.64" RatedVoltageAtBus1="11.0" RatedVoltageAtBus2="0.4" VectorGroup="Dz" IsTapChanging="false" LibraryComponentName="Distribution Transformer Rauscher &amp; Stoecklin AMTD, max 36 kV, 1000 kVA" LibraryComponentType="Distribution Transformer" Model="AMTD" Manufacturer="Rauscher &amp; Stoecklin" Bus1ID="bus_1" Bus2ID="bus_2" ConnectedAtBus1="true" ConnectedAtBus2="true" ID="transformer_1">
            <GIS ShapeType="Polygon">
                <Points>
                    <Point Lat="46.98848496732053" Lon="9.635973472749184"/>
                    <Point Lat="46.98816059608366" Lon="9.635973472749184"/>
                    <Point Lat="46.98816059608366" Lon="9.635887615896436"/>
                    <Point Lat="46.98848496732053" Lon="9.635887615896436"/>
                </Points>
            </GIS>
        </Transformer>
    </TRANSFORMER>
    <FEEDER>
        <Feeder HostBusID="bus_1" OperationalVoltageInPerUnit="1.0" OperationalAngleInRadians="0.0" MaxSourceShortCircuitPowerInMegavoltampere="550.0" MinSourceShortCircuitPowerInMegavoltampere="550.0" ReactanceToResistanceRatio="1.0" ID="networkfeeder_1"/>
    </FEEDER>
    <FUSE>
        <Fuse HostBranchID="connection_1" BranchEnd="Bus2" FuseType="Grid" LibraryFuseName="LV 400V 100A" ID="fuse_1"/>
    </FUSE>
    <PROTECTIONDEVICE/>
    <VOLTAGEREGULATOR/>
    <SWITCH>
        <Switch Type="Circuit Breaker" BranchEnd="Bus1" HostBranchID="transformer_1" ID="switch_1"/>
        <Switch Type="Circuit Breaker" BranchEnd="Bus2" HostBranchID="transformer_1" ID="switch_2"/>
    </SWITCH>
    <STATION/>
    <SHAPE/>
</GRID>

Endpoint referenceprofiles ​

Provides a list of available profiles reference profiles.

Change compared to v2 ​

  • removed unnecessary fields
  • using human readible ISO_8601 time stamps in response (instead of UNIX epoch milliseconds)

Example ​

GET https://your.domain.com/adaptricity/profiles returns:

json
{
  "DPGProtocolVersion": "3.0",
  "profiles": [
    {
      "profileID": "pv",
      "from": "2023-09-30T14:30:00Z",
      "to": "2023-09-30T15:30:00Z",
      "samplingTimeInSeconds": 900,
      "scaleWithRatedPowerBehavior": "PEAK_AT_RATED_POWER"
    },
    {
      "profileID": "wind",
      "from": "2023-09-30T14:30:00Z",
      "to": "2023-09-30T15:30:00Z",
      "samplingTimeInSeconds": 900,
      "scaleWithRatedPowerBehavior": "SCALE"
    }
  ]
}

Endpoint referenceprofile ​

Provides a active power profile for a specific profile-ID. Returns the entire range of available power data. Positive values represent load, negative values represent generation.

Change compared to v2 ​

  • Route provides all available data instead of requesting specific periods using timestamps
  • if reactive power is available, must provide same time range and sampling time as for active power
  • removed unnecessary fields
  • using human readible ISO_8601 time stamps in response (instead of UNIX epoch milliseconds)

Example ​

GET https://your.domain.com/adaptricity/profile/pv returns:

json
{
  "DPGProtocolVersion": "3.0",
  "profileID": "pv",
  "name": "Photovoltaic profile",
  "description": "Normalized profile from Bhadla Solar Park 2022",
  "from": "2023-09-30T14:30:00Z",
  "to": "2023-09-30T15:30:00Z",
  "samplingTimeInSeconds": 900,
  "activeResidualLoadInWatt": [
    -1843.0,
    -1967.0,
    -2145.0,
    -2004.0
  ]
}

In the future, we will also support 'reactiveResidualLoadInVar' in addition to 'activeResidualLoadInWatt'.

Endpoint meter (previously metermeasurements) ​

Providing active and reactive power measurements of a smart meter. Provides the range requested in the url. If available data doesn't cover requested time, activeResidualLoad and reactiveResidualLoad returns whatever is available in the requested range or empty arrays, if no data for the requested range is available.

For active power, positive values represent load, negative values represent generation. For reactive power, positive values represent capacitive power, negative values represent inductive power. For voltage, only positive values are allowed.

Change compared to v2 ​

  • the route can provide data non-continous data
  • add possibility to provide voltage data
  • if no data is available, the route provides no data instead of NaN-arrays
  • the units cannot be chosen (always Watt and Var)
  • removed unnecessary fields
  • renamed to meter (instead of metermeasurements)

Example ​

GET https://your.domain.com/adaptricity/meter/meter-0001/2023-09-30T14:30:00Z/2023-09-30T15:30:00Z returns:

json
{
  "DPGProtocolVersion": "3.0",
  "meterID": "meter-0001",
  "name": " 6925 Hollywood Blvd",
  "description": "TCL Chinese Theatre",
  "measurements": {
    "activeResidualLoadInWatt": [
      {
        "from": "2023-09-30T14:30:00Z",
        "to": "2023-09-30T15:30:00Z",
        "samplingTimeInSeconds": 900,
        "phaseABC": [
          1843.0,
          1967.0,
          2145.0,
          2004.0
        ]
      }
    ],
    "reactiveResidualLoadInVar": [
      {
        "from": "2023-09-30T14:30:00Z",
        "to": "2023-09-30T15:30:00Z",
        "samplingTimeInSeconds": 900,
        "phaseABC": [
          1843.0,
          1967.0,
          2145.0,
          2004.0
        ]
      }
    ],
    "voltageInVolt": [
      {
        "from": "2023-09-30T14:30:00Z",
        "to": "2023-09-30T15:30:00Z",
        "samplingTimeInSeconds": 900,
        "phaseABC": [
          412.0,
          411.5,
          409.1,
          413.8
        ]
      }
    ],
    "harmonicVoltageOrder1InVolt": [
      {
        "from": "2023-09-30T14:30:00Z",
        "to": "2023-09-30T15:30:00Z",
        "samplingTimeInSeconds": 900,
        "phaseABC": [
          412.0,
          411.5,
          409.1,
          413.8
        ]
      }
    ]
  }
}

Discontinued endpoints from API v2 ​

To simplify the interface, we got rid of some endpoints.

Endpoint timeranges ​

We don't provide this endpoint anymore, we instead request meter data according to what the user wants to simulate not knowing if data for that period is available using the meter endpoint

Endpoint transformers ​

We don't provide this endpoint anymore, instead add fields that used to provided by this endpoint directly in the grid transformer model:

  • maximumMeasuredApparentPowerInMegavoltampere
  • cosPhiAtMaximumApparentPower
  • cosPhiTypeAtMaximumApparentPower

Endpoint customers ​

We don't provide this endpoint anymore, instead add the loads and generators into the xml, provide a GDI project setting to calculate the load powers using the new properties from the grid transformer model (see above).

Endpoint slackbusmeasurements ​

We don't provide this endpoint anymore, instead we allow to import voltage data in the meter endpoint.