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/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. It is represented using ISO 8601 format and is always in UTC time, e.g. midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'.
PeriodTo	The timestamp until when the measured reading value is valid. If the reading is a momentaneous value, the Timestamp and PeriodTo should be set to the same value. If set to null or omitted from the payload, the register configured resolution will be used. It is represented using ISO 8601 format and is always in UTC time, e.g. midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'.
Value	The measured value of the reading.
Resolution (obsolete)	The resolution is phased out and not used anymore. If it is still sent as part of the payload it will be discarded and not used to calculate the timestamp until when the measured reading value is valid. You can use the PeriodTo instead to send the actual timestamp or rely on the default resolution configured on the register.

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