Programs | Switch Developer Documentation

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

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

500

Internal Server Error.

application/json

get

/programs

GET /api/openadr/v1/programs HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
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

201

Created.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

409

Conflict. Implementation dependent response if program with the same programName exists.

application/json

500

Internal Server Error.

application/json

post

/programs

POST /api/openadr/v1/programs HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
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

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

500

Internal Server Error.

application/json

get

/programs/{programID}

GET /api/openadr/v1/programs/{programID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
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

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

409

Conflict. Implementation dependent response if program with the same programName exists.

application/json

500

Internal Server Error.

application/json

put

/programs/{programID}

PUT /api/openadr/v1/programs/{programID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
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

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

500

Internal Server Error.

application/json

delete

/programs/{programID}

DELETE /api/openadr/v1/programs/{programID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
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
      ]
    }
  ]
}