DIAVASO CM Server API v2

Date Version Description

08/2018 2.0 Changes for CM version 0.35.X and higher
05/30/2019 2.1 Added service to export all meters in the inventory
The DIAVASO server API provides services below to perform the following tasks:

1. Import meters into the inventory

2. Delete meters from the inventory
3. Import routes
4. List all existing routes and their statuses
5. Assign a route to a reader
6. Export meters from the inventory
7. Export meters from a route (multiple routes must be export with different calls)
8. Delete a route
9. Delete readouts

All requests need to be encoded in JSON format using UTF-8 character set (appropriate HTTP header
needs to be set – Content-type: application/json; charset=utf-8). The server responds with
JSON responses.

Authentication
For the purpose of accessing server API a new user role was created. This role is called Service. All users
of this role can access the server API, but they are not allowed to login into UI. No other user role will be
allowed to access the server API. All requests authenticated with a user in a role other than Service will
fail with HTTP status code 402 Forbidden.

All requests must be authenticated and authorized. To authenticate a request the user credentials needs
to be provided. There are two ways how to provide it:

1. Request can contain query parameters user and password

2. Using standard HTTP Basic Access Authentication – it requires adding HTTP request header with
the user credentials, for example:

 Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

The string after Basic (in red) is Base64 encoded text in form of <user>:<password>
For this authentication user and password in query is not required.
Import Meters
/api/server/meters
POST /api/server/meters

Description
This service imports the given meters to the inventory.

Parameters

Name Located in Description Required Type

user Query User name NO string
password Query Password NO String
meters Body List of meters – The YES [ ImportMeterDTO ]
request body contains
JSON array of meters
dateTimeFormat Query Format of the date- NO String
time fields – default
format is yyyy-MM-dd
hh:mm:ss
update Query Update the existing NO true / false
meters. By default, this
option is false. If update
is false and a meter
with the same site ID
exists, the import will
fail.
createRoutes Query If the meter data NO true / false
contains routeName
and/or sequence fields
then the given routes
are created.
ignoreInvalid Query If set to true, the invalid NO true / false
meters are ignored and
correct meters are
imported

Responses

Code Description Schema

200 Success [ ImportAckDTO ]
 400 Bad Request – the request contains errors. [ ImportAckDTO ]
Either the body parameter is not valid JSON
object or the meters are not valid. If there are
some validation errors, these are return in the
response body as an array of errors.
See the Model section.
401 Unauthorized – wrong or missing user and
password
402 Forbidden – the specified user is not in the
correct role (Service)

Delete Meters
/api/server/meters
DELETE /api/server/meters

Description
This service deletes the given meters from the inventory. The meters are specified in the request body
as an array of strings (site IDs).

Parameters

Name Located in Description Required Type

user Query User name NO string
password Query Password NO string
meters Body Array of site IDs YES [ string, … ]

Responses

Code Description Schema

200, 204 Success
401 Unauthorized – wrong or missing user and
password
402 Forbidden – the specified user is not in the
correct role (Service)
404 Not found – the given metes do not exist
List All Existing Routes
/api/server/routes
GET /api/server/routes

Description
This service lists all existing routes.

Parameters

Name Located in Description Required Type

user Query User name NO string
password Query Password NO string

Responses

Code Description Schema

200 Success –The response body contains JSON [ RouteStatusDTO ]
array of route names (strings).
401 Unauthorized – wrong or missing user and
password
402 Forbidden – the specified user is not in the
correct role (Service)

Get Route Status

/api/server/route/{routeName}/status
GET /api/server/route/{routeName}/status

Description
This service returns status of the given route.

Parameters

Name Located in Description Required Type

user Query User name NO string
password Query Password NO String
routeName Query Route name YES String

Responses
 Code Description Schema
200 Success –The response body contains JSON RouteStatusDTO
array of route names (strings).
401 Unauthorized – wrong or missing user and
password
402 Forbidden – the specified user is not in the
correct role (Service)
404 Not found – the given route does not exist

Assign Route
/api/server/route/{routeName}/assign
POST /api/server/route/{routeName}/assign

Description
This service assigns the given route to the given user.

Parameters

Name Located in Description Required Type

user Query User name NO string
password Query Password NO String
assignTo Query Name of the user YES String
scheduledDate Query Date when the route is NO String
scheduled for read
dateFormat Query Format of the NO String
scheduled date –
default format is yyyy-
MM-dd

Responses

Code Description Schema

200, 204 Success
400 Bad Request – the request contains errors.
Either the user does not exist or scheduledDate
and/or dateFormat is invalid
401 Unauthorized – wrong or missing user and
password
402 Forbidden – the specified user is not in the
correct role (Service)
 404 Not found – the given route does not exist

Export Inventory
/api/server/inventory
GET /api/server/inventory

Description
This service exports all meters in the inventory.

Parameters

Name Located in Description Required Type

user Query User name NO String
password Query Password NO String
dateFormat Query Format of the date fields – default NO String
format is yyyy-MM-dd
dateTimeFormat Query Format of the date-time fields – NO String
default format is
yyyy-MM-dd hh:mm:ss
useMainUnit Query Export Value in main unit (i.e. m3, NO true / false
MWh, GJ)
historical Query If true, export historical readings NO true / false
type Query The type of historical readings. The NO String
following values can be specified:
 LATEST
 ALL
 DAILY
 MONTHLY
 YEARLY
startDate Query Date FROM which the readings are NO String
exported. Date must be specified in
dateFormat (or yyyy-MM-dd if the
date format not specified)
endDate Query Date TO which the readings are NO String
exported. Date must be specified in
dateFormat (or yyyy-MM-dd if the
date format not specified)

Responses
 Code Description Schema
200 Success – see the Model section. The response [ ExportMeterDTO ]
body contains JSON array of exported meters.
401 Unauthorized – wrong or missing user and
password
402 Forbidden – the specified user is not in the
correct role (Service)

Export Route
/api/server/route/{routeName}
GET /api/server/route/{routeName}

Description
This service exports meters for the given route.

Parameters

Name Located in Description Required Type

user Query User name NO String
password Query Password NO String
routeName Path Route name YES String
dateFormat Query Format of the date fields – default NO String
format is yyyy-MM-dd
dateTimeFormat Query Format of the date-time fields – NO String
default format is
yyyy-MM-dd hh:mm:ss
useMainUnit Query Export Value in main unit (i.e. m3, NO true / false
MWh, GJ)
readOnly Query If true, export read routes only NO true / false
historical Query If true, export historical readings NO true / false
type Query The type of historical readings. The NO String
following values can be specified:
 LATEST
 ALL
 DAILY
 MONTHLY
 YEARLY
startDate Query Date FROM which the readings are NO String
exported. Date must be specified in
dateFormat (or yyyy-MM-dd if the
 date format not specified)
endDate Query Date TO which the readings are NO String
exported. Date must be specified in
dateFormat (or yyyy-MM-dd if the
date format not specified)

Responses

Code Description Schema

200 Success – see the Model section. The response [ ExportMeterDTO ]
body contains JSON array of exported meters.
401 Unauthorized – wrong or missing user and
password
402 Forbidden – the specified user is not in the
correct role (Service)
404 Not found – the given route does not exist

Delete Route
/api/server/route/{routeName}
DELETE /api/server/route/{routeName}

Description
This service deletes the given route.

Parameters

Name Located in Description Required Type

user Query User name NO string
password Query Password NO string
routeName Path Route name YES string

Responses

Code Description Schema

200, 204 Success
401 Unauthorized – wrong or missing user and
password
402 Forbidden – the specified user is not in the
correct role (Service)
 404 Not found – the given route does not exist

Delete Readouts
/api/server/readouts
DELETE /api/server/readouts

Description
This service deletes all readouts in the system from beginning to the given date.
Parameters

Name Located in Description Required Type

user Query User name NO string
password Query Password NO string
toDate Path Date to which YES string
the readouts are
deleted.
dateFormat Query Format of the NO String
date fields –
default format is
yyyy-MM-dd

Responses

Code Description Schema

200, 204 Success
401 Unauthorized – wrong or missing user and
password
402 Forbidden – the specified user is not in the
correct role (Service)
404 Not found – the given route does not exist
Models
This section details the definition of the models.

ImportMeterDTO {
# This model describes a meter data for the import
amrChannel: string *
amrDevice: string
amrMeterId: string
adcUnit: string
averageDailyConsumption: number (double)
city: string
customFields: { CUSTOM_FIELD1: string, … }
customerInfo: string
customerName: string
exDate: string (date-time)
exMeterId: string
exUnit: string
exValue: number (int64)
latitude: number (double)
longitude: number (double)
meterLocation: string
permissibleRelativeDeviation: number (double)
pulseWeight: number (double)
repeaterAddress: string
repeaterLatitude: number (double)
repeaterLongitude: number (double)
routeName: string
sequence: number (int32)
siteId: string *
siteNo: string
siteRemark: string
srfAddress: string
srfKey: string
stN1: string
stN2: string
street: string
unit: string *
zip: string
}

ImportAckDTO {
# This model describes result of the operation
status: string # OK or FAIL
errors: [ ImportErrorDTO ] # list of error in case of FAIL
}

ImportErrorDTO {
# This model describes a single error in import data.
index: number (int32) # index of the meter in the data
error: string # description of the error
field: string # field name where the error occurred
}

RouteStatusDTO {
# This model describes a status of a route
routeName: string # route name
status: string # status of the route
Possible values:
 "DEFINED"
 "ASSIGNED"
 "IN_PROGRESS"
 "FINISHED"

meterCount: number (int32) # number of meters in the route

readCount: number (int32) # number of read meters
}

ExportMeterDTO {
# This model describes a meter data for the export
amrChannel: string
amrDevice: string
amrMeterId: string
adcUnit: string
averageDailyConsumption: number (double)
city: string
customFields: { CUSTOM_FIELD1: string, … }
customerInfo: string
customerName: string
latitude: number (double)
longitude: number (double)
meterLocation: string
permissibleRelativeDeviation: number (double)
pulseWeight: number (double)
repeaterAddress: string
repeaterLatitude: number (double)
repeaterLongitude: number (double)
readouts: [ ExportReadoutDTO ] # list of readouts
siteId: string
siteNo: string
siteRemark: string
srfAddress: string
srfKey: string
stN1: string
stN2: string
street: string
unit: string
zip: string
}
ExportReadoutDTO {
# This model describes readout data
actualDateAndTime: string (date-time)
airInServiceEnd: string (date-time)
airInServiceStart: string (date-time)
alarms: [ string ]
alarmActiveInformation: string (byte)
amrMeterId: string
averageDailyConsumption: number (double)
backflowEnd: string (date-time)
backflowStart: string (date-time)
backwardVolume: number (int32)
batteryEndDetected: string (date-time)
batteryLowDetected: string (date-time)
batteryRemaining: string (date-time)
brokenPipeEnd: string (date-time)
brokenPipeParams: string
brokenPipeStart: string (date-time)
comment: string
currentFlow: number (int32)
customFields: {
CUSTOM_FIELD1: string, …
}
customerSpecificText: string
date: string (date)
dayOfTheMonth: number (int32)
directionDetection: number (int32)
enhancedMbusAddress: number (int64)
fixedDateReadingContent: number (int32)
historicalErrorLimit: number (int32)
latInterval: number (int32)
leakEnd: string (date-time)
leakStart: string (date-time)
leakageParams: string (byte)
logContent: number (int32)
loggingInterval: number (int32)
mBusStatus: string
mBusTransmissionInterval: number (int32)
magneticTamperEnd: string (date-time)
magneticTamperStart: string (date-time)
maximumFlow: number (int32)
meterId: string
meterLocation: string
meterSerialId: number (int32)
meterSizeId: number (int32)
moduleRemovedEnd: string (date-time)
moduleRemovedStart: string (date-time)
numberOfDials: number (int32)
permissibleRelativeDeviation: number (double)
pulseWeight: number (double)
readoutStatus: string
 Possible values:
 "MANUAL_READ"
 "NOT_READ"
 "IN_PROGRESS"
 "AUTOMATIC_READ"
 "AUTOMATIC_READ_ALARM"
 "WRONG_KEY"
 "WRONG_KEY_READ_MANUALLY"
semiPulseWeight: number (double)
semiType: string
Possible values:
 "UNKNOWN"
 "E_REGISTER"
 "I_PERL"
 "PULSE_RF"
semiUnit: string
timeOfFDRReset: string (date-time)
timeOfLogReset: string (date-time)
timeOfMaximumFlow: string (date-time)
type: string
Possible values:
 "IMPORT"
 "MANUAL"
 "BUP"
 "SEMI"
 "WMBUS"
 "FDR"
transmissionInterval: number (int32)
unit: string
value: number (int64)

wmbusManufacturer: string
wmbusGeneration: number (int32)
wmbusSerial: string
wmbusUserSerial: string
wmbusUserManufacturer: string
wmbusDevice: number (int32)
wmbusVersion: number (int32)
wmbusMedium: number (int32)
plainAlarms: number (int32) # wmbus alarms
wmbusCounters: [ ExportWMbusCounterDTO ] # list of
counters
}
ExportWMbusCounterDTO {
# This model describes wmbus counter
order: number (int32)
storage: number (int64)
tariff: number (int32)
subUnit: number (int32)
type: string # function field
Possible values:
 "INST" # Instantaneous value
 "MAX" # Maximum value
 "MIN" # Minimum value
 "ERROR" # Value during error state
vif: number (int32) # value info field
vifType: string # value info field text description
flow: boolean
customDescription: string
value: number (double)
unit: string
}
Formats
The models must be encoded in valid JSON format. The following table defines the format for the field
types.

Type Description
string Any character string encoded in UTF-8 character set
Number (int32/int64) A valid JSON integer number
number (double) A valid JSON floating point value (e.g.: 21.4548)
date (string) A string in the form of yyyy-MM-dd. The date and time is specified
according to server time zone.
date-time (string) A string in the form of yyyy-MM-dd hh:mm:ss. The date and time is
specified according to server time zone.

Some of the fields from ImportMeterDTO must be in specific format. The table below defines the
formats.

Field Type Format

amrChannel M AMR Channel can be provided in the following formats:
 0 or "Manual" (means manual read)
 7 or "SensusRF" (means automatic read)
unit M Unit can be one of these:
 "m3" -- cubic meters
 "l" -- liters
 "IGal" -- imperial gallons
 "Gal" -- US gallons
 "kWh" -- kilowatt hours
 "MWh" -- megawatt hours
 "MJ" -- mega joules
 "GJ" -- gigajoules
 "ft3" -- cubic feet
 "kg" – kilograms
srfAddress SM SRF Address can be provided in the following formats:
 1011-000-2411
 10110002411
 110002411
 0x68e80eb
srfKey SM SRF Key can be provided in the following formats:
 32 hexadecimal digits
 When empty value is provided Sensus default key will be
imported
exMeterId SM Meter ID can be provided in the following formats:
 8SEN0110043816
 8SEN429-011-2213
pulseWeight SM mandatory only for PulseRF and Meistream meters
Pulse Weight is mainly used with imported Unit when fast mode
readout was done (otherwise data from SEMI are used)
 Pulse Weight is shown in meter detail on server only

For display a value with unit in CM (both server and Android) only these
units are permitted (ml, l, m3, Wh, kWh, MWh, kJ, MJ, GJ, Gal (UK), Gal
(US), mft3, kg)

For other units the unit and value have to be transformed to one of the
above units with use of Pulse Weight, e.g.
15 dcl (unit: milliliter; Pulse Weight: 100) = 1 500 ml

Pulse weight can be provided in the following formats:

 "l" (0.000001 - 655 350)
 "m3" (0.000000001 - 655.350)
 "IGal" (0.000000001 - 655 350 000)
 "Gal" (0.000000001 - 655 350 000)
 "kWh" (0.000001 - 655 350)
 "MWh" (0.000000001 - 655.350)
 "MJ" (0.000001 - 655 350)
 "GJ" (0.000000001 - 655.350)
 "ft3" (0.000000001 - 655 350 000)
 "kg" (0.000000001 - 655 350 000)
repeaterAddress O Repeater Address can be provided in the following formats:
 2021-000-0098
 210000098
 0x0c8458e2
Examples
Getting List of all Routes

This example shows how to get the list of all routes and their statuses. The user is authenticated using
user and password in the request URL.

Request URL:
GET http://<server>/SensusServer/api/server/routes?user=service&password=service

Request Headers:
Content-type: application/json; charset=utf-8

Response (HTTP Status Code 200):

[
{
"routeName": "TEST1",
"status": "FINISHED",
"meterCount": 2,
"readCount": 2
},
{
"routeName": "TEST2",
"status": "ASSIGNED",
"meterCount": 5,
"readCount": 0
}
]

Getting Status of a particular Route

This example shows how to get status of route TEST1. The user is authenticated using HTTP Basic Access
Authentication request header. The credentials are encoded using Base64 encoding.

Request URL:
GET http://<server>/SensusServer/api/server/route/TEST1/status

Request Headers:
Content-type: application/json; charset=utf-8
Authorization: Basic c2VydmljZTpzZXJ2aWNl

Response (HTTP Status Code 200):

{
"routeName": "TEST1",
"status": "FINISHED",
"meterCount": 2,
"readCount": 2
}
Importing a Meters

This example shows how to import meters. Authentication done using HTTP request header.

Request URL:
POST http://<server>/SensusServer/api/server/meters?update=true&dateFormat=yyyy-MM-
dd&createRoutes=true

Request Headers:
Content-type: application/json; charset=utf-8
Authorization: Basic c2VydmljZTpzZXJ2aWNl

Request BODY:
[
{
"routeName":"TEST1",
"sequence":2,
"siteId":"156446",
"street":"Dornych",
"stN1":"90",
"city":"Brno",
"siteRemark":"Be aware of dogs",
"customerName":"Jan Novak",
"unit":"m3",
"exMeterId":"8SEN0310001135",
"pulseWeight":1,
"amrChannel":"SensusRF",
"amrDevice":"eRegister 433",
"srfAddress":"1031-000-1135"
}
]

Success Response (HTTP Status Code 200):

{
"status": "OK",
"errors": []
}

Error Response (HTTP Status Code 400):

{
"status": "FAIL",
"errors": [ {
"index": 1,
"field": "srfAddress",
"error": "invalid value for field 'srfAddress': '1031-000-1135x'"
}
]
}
Import Routes

This example shows how to import routes. Authentication done using HTTP request header.

Request URL:
POST http://<server>/SensusServer/api/server/routes

Request Headers:
Content-type: application/json; charset=utf-8
Authorization: Basic c2VydmljZTpzZXJ2aWNl

Request BODY:
[
{
"siteId":"11065215404",
"sequence":1,
"routeName":"TEST3"
},
{
"siteId":"11065215405",
"sequence":2,
"routeName":"TEST3"
}
]

Success Response (HTTP Status Code 200):

{
"status": "OK",
"errors": []
}

Assigning a Route

This example shows how to assign route TEST1 to user reader. Authentication done using HTTP request
header.

Request URL:
POST http://<server>/SensusServer/api/server/route/TEST1/assign?assignTo=reader&
scheduledDate=2017-05-20

Request Headers:
Content-type: application/json; charset=utf-8
Authorization: Basic c2VydmljZTpzZXJ2aWNl

Response (HTTP Status Code): 204

Exporting a Route

This example shows how to export route TEST1. Authentication done using HTTP request header.

Request URL:
GET
http://<server>/SensusServer/api/server/route/TEST1?readOnly=false&historical=true&type=ALL&st
artDate=1/1/2018&endDate=1/12/2018&dateFormat=dd/MM/yyyy&dateTimeFormat=dd/MM/yyyy%20HH:mm

Request Headers:
Content-type: application/json; charset=utf-8
Authorization: Basic c2VydmljZTpzZXJ2aWNl

Success Response (HTTP Status Code): 200

[
{
"siteId":"156446",
"street":"Dornych",
"stN1":"90",
"city":"Brno",
"siteRemark":"Be aware of dogs",
"customerName":"Jan Novak",
"pulseWeight":1,
"amrChannel":"SensusRF",
"amrDevice":"eRegister 433",
"srfAddress":"1031-000-1135",
"srfKey":"DEFAULT",
"customFields":{ },
"readouts":[
{
"type":"FDR",
"date":"01/08/2018 02:00",
"meterId":"8SEN0310001004",
"readoutStatus":"AUTOMATIC_READ",
"value":1893.73,
"unit":"m3",
"alarms":[]
},
{
"type":"FDR",
"date":"01/09/2018 02:00",
"meterId":"8SEN0310001004",
"readoutStatus":"AUTOMATIC_READ",
"value":1893.72,
"unit":"m3",
"alarms":[]
},
{
"type":"FDR",
"date":"01/10/2018 02:00",
"meterId":"8SEN0310001004",
"readoutStatus":"AUTOMATIC_READ",
"value":1893.72,
"unit":"m3",
 "alarms":[]
},
{
"type":"SEMI",
"date":"31/10/2018 09:31",
"meterId":"8SEN0310001004",
"readoutStatus":"AUTOMATIC_READ",
"value":1893728.14,
"unit":"m3",
"semiType":"E_REGISTER",
"transmissionInterval":5,
"latInterval":0,
"currentFlow":0,
"backwardVolume":962.83,
"mBusStatus":1,
"mBusTransmissionInterval":14400,
"alarmActiveInformation":-20,
"leakageParams":0,
"brokenPipeParams":6,
"batteryRemaining":"08/07/2029 16:00",
"maximumFlow":0.01,
"timeOfMaximumFlow":"31/10/2018 09:31",
"logContent":8191,
"loggingInterval":60,
"fixedDateReadingContent":8191,
"dayOfTheMonth":1,
"actualDateAndTime":"31/10/2018 09:30",
"historicalErrorLimit":29,
"customerSpecificText":"",
"timeOfFDRReset":"30/01/2018 15:00",
"timeOfLogReset":"30/01/2018 15:00",
"meterSizeId":16,
"meterSerialId":310001004,
"numberOfDials":9,
"alarms":[]
},
{
"type":"BUP",
"date":"31/10/2018 09:50",
"meterId":"8SEN0310001004",
"readoutStatus":"AUTOMATIC_READ",
"value":1893728.12,
"unit":"m3",
"alarms":[]
}
]
}
]
Exporting the inventory

This example shows how to export all meters in the inventory. Authentication done using HTTP request
header.

Request URL:
GET
http://<server>/SensusServer/api/server/inventory?historical=true&type=ALL&startDate=1/1/2018&
endDate=1/12/2018&dateFormat=dd/MM/yyyy&dateTimeFormat=dd/MM/yyyy%20HH:mm

Response format and error codes for this service call are identical as for exporting a route.

Deleting a Route

This example shows how to delete route TEST1. Authentication done using HTTP request header.

Request URL:
DELETE http://<server>/SensusServer/api/server/route/TEST1

Request Headers:
Content-type: application/json; charset=utf-8
Authorization: Basic c2VydmljZTpzZXJ2aWNl

Response (HTTP Status Code): 204