Concepts

Learn about the main concepts used in the Switch platform.

Throughout the Switch user guide and developer documentation, there are different concepts, variables, and terms used.

Below you can find more information about these concepts and where to find them in the Switch app.

<organizationId>

A unique identifier of an Organization in the Switch platform. To find the organization ID, open the Switch app, select the organization for which you want to see the ID (for how to select organization see the Switch User Guide), click on the Settings/Administer my organization top-right menu link and then in the left side menu click on the API/Integration testing tab.

The organization identifier is needed by most of the Switch API endpoints, either passed as a query parameter or part of the request payload.

<userId>

A unique identifier of a User in Switch. You can find your User ID or see every organization user ID in the users list under Settings/Administer my organization/Users page.

Switch platform differentiates between two types of users, Human and Application. Real persons are represented as users of type Human. The Switch API clients such as Organization Clients and VTN Credentials are represented as users of type Application.

<resourceId>

A unique identifier of a Resource in Switch. You can find your organization resources and their IDs under Settings/Administer my organization/Resources page.

Meter

A meter represents any kind of metering device or system used by a utility, which is capable of measuring or recording the quantity of services delivered or received by a customer.

Each meter is defined by:

Attribute	Description
Name	The name of the meter. Required attribute.
Type	The type of the meter which most of the time is the Default. Required attribute.
External ID	Platform unique identifier for the meter. Required attribute.
Coordinates	Optional coordinates where the meter is placed.
Registers	A meter contains one or multiple registers. See Register.

A meter can be configured to belong to one or multiple organizations in the Switch platform.

Register

A register represents a part of the meter which can measure or record only one type of measurement, such as power, voltage, current, pressure etc.

Each register is defined by:

Attribute	Description
Name	The name of the register. Required attribute.
External ID	Unique identifier of the register in the scope of a meter. Required attribute.
Default resolution	The default resolution in seconds of the measurements provided by the register, e.g. hourly measurements. Required attribute.
Measurement type	The type of measurements provided by the register, e.g. active power. Required attribute.
Measurement prefix	The measurement prefix of the measurements provided by the register, e.g. if the register provides measurements for active power in kW then the measurement prefix will be Kilo. Required attribute.
Readings	A register provides measurements which are called readings. See Reading.

There are special types of registers called virtual registers. These registers generate virtual readings based on readings from other source registers and the selected calculation type.

Reading

A reading represents one measurement from register.

Each reading is defined by:

Attribute	Description
Timestamp	The timestamp when the reading value was measured.
Value	The measured value of the reading.
Resolution	Indicates the length of the time window (in seconds) that the reading is valid for. E.g. a resolution of 3600 and a timestamp of 2024-01-01T12:00:00.00Z means that the reading is an hourly average for the period from 2024-01-01T12:00:00.00Z - 2014-01-01T13:00:00.00Z. If the reading is a momentaneous value, the resolution should be set to 0. If set to null, the register default resolution will be assumed.

More information about sending readings to the Switchmarket platform can be found on our Guides page.