Basic requests group

This group contains the following requests:

Request	URL
events	<url_smartroad>/api/<version>1.Versions/events
status	<url_smartroad>/api/<version>/status
stat	<url_smartroad>/api/<version>/stat
sensors	<url_smartroad>/api/<version>/sensors

This request group has extra request parameters, request parameters format and error handling sections in common. Request definition and data schema are unique for each request and stated in its corresponding sections.

Extra request parameters

List of allowed extra request parameters:

• sensorId
• sensorName DEPRECATED
• project_id
• startDate / from
• endDate / to
• timeZone

Request parameters format

Date interval:

Parameter: startDate/endDate

-----------------------------
startDate | 14.03.2025 13:00
endDate   | 14.03.2025 13:15
-----------------------------

Possible parameters:

• startDate/endDate

Possible values:

• 14.03.2025 13:00 / 14.03.2025 14:00
• 14.03.2025 13 / 14.03.2025 14
• 14.03.2025 13:00:00 / 14.03.2025 14:00:00

Parameter: from/to

-----------------------------
from | 2025-03-14T13:00:00
to   | 2025-03-14T13:15:00
-----------------------------

Possible parameters:

• from/to

Possible values:

• 2025-03-14T13:00:00 / 2025-03-14T14:00:00
• 2025-03-14T13:00 / 2025-03-14T14:00
• 2025-03-14T13 / 2025-03-14T14
• 2025-03-14 13:00:00 / 2025-03-14 14:00:00
• 2025-03-14 13:00 / 2025-03-14 14:00
• 2025-03-14 13 / 2025-03-14 14

Parameters work only in pairs. Setting both start and end of time period is necessary. Parameters are register independent.

Parameter: timeZone

--------------------------
timezone | Europe/Moscow
--------------------------

Possible parameter:

• timeZone

Possible values:

• default: Europe/Moscow
• UTC
• Chile/Continental
• America/Indiana/Knox

As values, it's possible to use the full name of time zone or time zone abbreviations. It's allowed to pass only 1 value. Parameter is register independent.

A few time zone examples are listed in the following table. The time zone value from the table is passing in <region>/<country>/<city> format. If one of the parts is missing, then the value passes without this part and a following slash.

Value examples

Offset	Region	Country, island, territory	City, station, territory
0	UTC
+3	Europe		Istanbul, Moscow
	Asia		Istanbul
+4	Europe		Samara, Astrakhan, Ulyanovsk, Saratov
+7	Asia		Tomsk, Novokuznetsk, Krasnoyarsk, Barnaul, Novosibirsk
	Indian	Christmas
+10	Asia		Vladivostok, Ust-Nera
-3		Chile	Continental
		Brazil	East
-9.5	Australia	North

Project data:

Parameter: project_id

------------------------------------------------
project_id | 00112233-4455-6677-8899-aabbccddeeff
------------------------------------------------

Possible parameter:

• project_id

It's allowed to pass only 1 value. Parameter is register independent.

Sensor data:

Parameter: sensorId

------------------------------------------------
sensorId | 00112233-4455-6677-8899-aabbccddeeff
------------------------------------------------

Possible parameter:

• sensorId
• sensorID
• sensor_id

It's allowed to pass more than 1 value:

00112233-4455-6677-8899-aabbccddeeff,99887766-5544-3322-1100-ffeeddccbbaa

Values are divided by comma with no gaps. Parameter is register independent.

Parameter: sensorName

------------------------
sensorName | example
------------------------

Possible parameter:

• sensorName
• name

Parameter is register independent. It's allowed to pass more than 1 value. When adding multiple sensors in request, it's important for sensors to be from the same project, otherwise request response will be 400 Bad Request.

Error handling

Sending only start of the time interval

--------------------------------
startDate | 14.03.2025 13:00
          |     //endDate missing 
--------------------------------

the following response is expected to be received:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "Ошибка проверки параметров: Указано начало периода, но не указано окончание"
}

Sending only end of the time interval

--------------------------------
        |     //startDate missing 
endDate | 14.03.2025 14:00
--------------------------------

the following response is expected to be received:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "Ошибка проверки параметров: Указано окончание периода, но не указано начало"
}

Sending time parameter in wrong format

--------------------------------
startDate | 2025-03-14T13:00:00
endDate   | 2025-03-14T14:00:00
--------------------------------

or

--------------------------------
from | 14.03.2025 13:00
to   | 14.03.2025 14:00
--------------------------------

the following response is expected to be received:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "JSON transformation failed: Error processing rule for filters.range_start: date/time field value out of range: \"14.03.2025 13:00\""
}

Sending sensor ID parameter in wrong format

-------------------------------------------------
sensorId | 00112233-4455-6677-8899-aabbccddeef
         |    //UUID wrong length (short)
-------------------------------------------------

-------------------------------------------------
sensorId | 00112233-4455-6677-8899-aabbccddeeffg
         |    //UUID wrong length (long)
-------------------------------------------------

the following response is expected to be received:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "JSON transformation failed: Invalid UUID format for filters.sensors: \"<sensorId>\""
}

Sending project ID parameter in wrong format

-------------------------------------------------
project_id | 00112233-4455-6677-8899-aabbccddeef
           |    //UUID wrong length (short)
-------------------------------------------------

-------------------------------------------------
project_id | 00112233-4455-6677-8899-aabbccddeeffg
           |    //UUID wrong length (long)
-------------------------------------------------

the following response is expected to be received:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "JSON transformation failed: Invalid UUID format for filters.projects: \"<project_id>\""
}

Sending request parameters:

• with wrong sensor name or ID
• if user don't have permission for the selected sensor
• if selected sensors are from different projects

the following response is expected to be received:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "Ошибка проверки параметров: Указанные параметры или права пользователя не позволяют однозначно определить ИД проекта"
}

Sending time zone parameter in wrong format, the following response is expected to be received:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "invalid value for parameter \"TimeZone\": \"<incorrect_timezone>\""
}

---

1. Value of the parameter “version” depends on API user organization. Default value is “2.0”. Any other endpoint (ex. “integration”) can be used as well.↩