Programs

searches all programs

get

List all programs known to the server. May filter results by targetType and targetValues as query params. Use skip and pagination query params to limit response size.

Authorizations

Query parameters

targetTypestringOptional

Indicates targeting type, e.g. GROUP

targetValuesstring[]Optional

List of target values, e.g. group names

skipinteger · int32Optional

number of records to skip for pagination.

limitinteger · int32 · max: 50Optional

maximum number of records to return.

Responses

get

HTTPcURLJavaScriptPython

GET /api/openadr/v1/programs HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer JWT
Accept: */*

[
  {
    "id": "object-999",
    "createdDateTime": "2023-06-15T09:30:00Z",
    "modificationDateTime": "2023-06-15T09:30:00Z",
    "objectType": "PROGRAM",
    "programName": "ResTOU",
    "programLongName": "Residential Time of Use-A",
    "retailerName": "ACME",
    "retailerLongName": "ACME Electric Inc.",
    "programType": "PRICING_TARIFF",
    "country": "US",
    "principalSubdivision": "CO",
    "timeZoneOffset": "PT1H",
    "intervalPeriod": {
      "start": "2023-06-15T09:30:00Z",
      "duration": "PT1H",
      "randomizeStart": "PT1H"
    },
    "programDescriptions": [],
    "bindingEvents": false,
    "localPrice": false,
    "payloadDescriptors": [
      {
        "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
        "payloadType": "PRICE",
        "units": "KWH",
        "currency": "USD"
      }
    ],
    "targets": [
      {
        "type": "PRICE",
        "values": [
          0.17
        ]
      }
    ]
  }
]

create a program

post

Create a new program in the server.

Authorizations

Body

Provides program specific metadata from VTN to VEN.

idstring · min: 1 · max: 128Optional

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

createdDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

modificationDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

objectTypestring · enumOptional

Used as discriminator

Possible values:

programNamestring · min: 1 · max: 128Required

Short name to uniquely identify program.

Example: ResTOU

programLongNamestring | nullableOptional

Long name of program for human readability.

Default: nullExample: Residential Time of Use-A

retailerNamestring | nullableOptional

Short name of energy retailer providing the program.

Default: nullExample: ACME

retailerLongNamestring | nullableOptional

Long name of energy retailer for human readability.

Default: nullExample: ACME Electric Inc.

programTypestring | nullableOptional

A program defined categorization.

Default: nullExample: PRICING_TARIFF

countrystring | nullableOptional

Alpha-2 code per ISO 3166-1.

Default: nullExample: US

principalSubdivisionstring | nullableOptional

Coding per ISO 3166-2. E.g. state in US.

Default: nullExample: CO

timeZoneOffsetstringOptional

duration in ISO 8601 format

Default: PT0SExample: PT1HPattern: ^(-?)P(?=\d|T\d)(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)([DW]))?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$

bindingEventsboolean | nullableOptional

True if events are fixed once transmitted.

Default: nullExample: false

localPriceboolean | nullableOptional

True if events have been adapted from a grid event.

Default: nullExample: false

Responses

post

HTTPcURLJavaScriptPython

POST /api/openadr/v1/programs HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 679

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "PROGRAM",
  "programName": "ResTOU",
  "programLongName": "Residential Time of Use-A",
  "retailerName": "ACME",
  "retailerLongName": "ACME Electric Inc.",
  "programType": "PRICING_TARIFF",
  "country": "US",
  "principalSubdivision": "CO",
  "timeZoneOffset": "PT1H",
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "programDescriptions": [],
  "bindingEvents": false,
  "localPrice": false,
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "PROGRAM",
  "programName": "ResTOU",
  "programLongName": "Residential Time of Use-A",
  "retailerName": "ACME",
  "retailerLongName": "ACME Electric Inc.",
  "programType": "PRICING_TARIFF",
  "country": "US",
  "principalSubdivision": "CO",
  "timeZoneOffset": "PT1H",
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "programDescriptions": [],
  "bindingEvents": false,
  "localPrice": false,
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

searches programs by program ID

get

Fetch the program specified by the programID in path.

Authorizations

Path parameters

programIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Responses

get

HTTPcURLJavaScriptPython

GET /api/openadr/v1/programs/{programID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer JWT
Accept: */*

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "PROGRAM",
  "programName": "ResTOU",
  "programLongName": "Residential Time of Use-A",
  "retailerName": "ACME",
  "retailerLongName": "ACME Electric Inc.",
  "programType": "PRICING_TARIFF",
  "country": "US",
  "principalSubdivision": "CO",
  "timeZoneOffset": "PT1H",
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "programDescriptions": [],
  "bindingEvents": false,
  "localPrice": false,
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

update a program

put

Update an existing program with the programID in path.

Authorizations

Path parameters

programIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Body

Provides program specific metadata from VTN to VEN.

idstring · min: 1 · max: 128Optional

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

createdDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

modificationDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

objectTypestring · enumOptional

Used as discriminator

Possible values:

programNamestring · min: 1 · max: 128Required

Short name to uniquely identify program.

Example: ResTOU

programLongNamestring | nullableOptional

Long name of program for human readability.

Default: nullExample: Residential Time of Use-A

retailerNamestring | nullableOptional

Short name of energy retailer providing the program.

Default: nullExample: ACME

retailerLongNamestring | nullableOptional

Long name of energy retailer for human readability.

Default: nullExample: ACME Electric Inc.

programTypestring | nullableOptional

A program defined categorization.

Default: nullExample: PRICING_TARIFF

countrystring | nullableOptional

Alpha-2 code per ISO 3166-1.

Default: nullExample: US

principalSubdivisionstring | nullableOptional

Coding per ISO 3166-2. E.g. state in US.

Default: nullExample: CO

timeZoneOffsetstringOptional

duration in ISO 8601 format

Default: PT0SExample: PT1HPattern: ^(-?)P(?=\d|T\d)(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)([DW]))?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$

bindingEventsboolean | nullableOptional

True if events are fixed once transmitted.

Default: nullExample: false

localPriceboolean | nullableOptional

True if events have been adapted from a grid event.

Default: nullExample: false

Responses

put

HTTPcURLJavaScriptPython

PUT /api/openadr/v1/programs/{programID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 679

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "PROGRAM",
  "programName": "ResTOU",
  "programLongName": "Residential Time of Use-A",
  "retailerName": "ACME",
  "retailerLongName": "ACME Electric Inc.",
  "programType": "PRICING_TARIFF",
  "country": "US",
  "principalSubdivision": "CO",
  "timeZoneOffset": "PT1H",
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "programDescriptions": [],
  "bindingEvents": false,
  "localPrice": false,
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "PROGRAM",
  "programName": "ResTOU",
  "programLongName": "Residential Time of Use-A",
  "retailerName": "ACME",
  "retailerLongName": "ACME Electric Inc.",
  "programType": "PRICING_TARIFF",
  "country": "US",
  "principalSubdivision": "CO",
  "timeZoneOffset": "PT1H",
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "programDescriptions": [],
  "bindingEvents": false,
  "localPrice": false,
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

delete a program

delete

Delete an existing program with the programID in path.

Authorizations

Path parameters

programIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Responses

delete

HTTPcURLJavaScriptPython

DELETE /api/openadr/v1/programs/{programID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer JWT
Accept: */*

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "PROGRAM",
  "programName": "ResTOU",
  "programLongName": "Residential Time of Use-A",
  "retailerName": "ACME",
  "retailerLongName": "ACME Electric Inc.",
  "programType": "PRICING_TARIFF",
  "country": "US",
  "principalSubdivision": "CO",
  "timeZoneOffset": "PT1H",
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "programDescriptions": [],
  "bindingEvents": false,
  "localPrice": false,
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}