Documentation
API Reference

API Reference

This section provides a description of the platform’s Web API, implemented as a REST-API data package for exchange in JSON format.

Getting Started

General Terms

  • Data Transfer Format The Web API is implemented as a REST-API data package for exchange in JSON format.

  • Authentication Procedure Authentication is based on a dynamically updated token, which guarantees the security of the data received and prevents token leakage.

  • Format of Variables Containing Date and Time The Web API returns data of the date and time type in UNIX time or POSIX time encoding in the format UTC: 1613376963. When converting Unix time to a understandable date, you must specify the time zone.

  • Pagination The Web API implements pagination functionality for page-by-page loading of data. Passed by parameter: page="page number" (page=1). The number of records returned in the query can be specified by the per_page parameter, but no more than 1000 records.

Authentication

Authentication is based on a dynamically updated token. In practice, it looks like this:

  • Primary authentication is performed using an email and password existing in the system and a dynamic token and related attributes are received in response.
  • Forming a target request to receive data with the token received in the previous step added to the HTTP request headers.
  • Sending a request to the server. If the request is formed correctly, the server returns data in the response body and a new token in the response headers, while the old token becomes invalid. With a new token, we can repeat the previous step and so on.
  • Upon completion of the work, the last token can be made invalid before its expiration date (SignOut).

Note

To summarize, it turns out that each subsequent request to the WEB-API must contain 4 headers from the previous response.

Initial authentication uses the email and password of an existing user. To do this, you need to send a POST request to the address:

https://uztgs.uz/api/v1/auth/sign_in

An example request in Curl format:

curl -i --header "Content-Type: application/json" \
     --request POST \
     --data '{"email":"api@local.net","password":"Str0ngPas$"}'\
     https://uztgs.uz/api/v1/auth/sign_in

In response we will receive the following message:

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block X-Content-Type-Options: nosniff X-Download-Options: noopen X-Permitted-Cross-Domain-Policies: none Referrer-Policy: strict-origin-when-cross-origin Content-Type: application/json; charset=utf-8 access-token: tgervk9_9xicJYpmSsnnNA
token-type: Bearer
client: D-Uv3ER53873olhnNLjL9w
expiry: 1615227012
uid: api@local.net
ETag: W/"5b9bcc76f7223b72b79d9f2d31ff0fd5"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: c18e06b4-e5bd-40b5-875d-7ac958e2fbb5
X-Runtime: 0.391069
Transfer-Encoding: chunked
{"data":{"id":6,"email":"api@local.
net","provider":"email","uid":"api@local.net","name":"API user"}}

In this answer we are interested in the following headings:

Заголовок Описание
access_token The value of this header is used as a password for each request. The value changes with each request.
client This header is unique to the current connection. Allows multiple active sessions at the same time.
expiry The time when this token will expire. Default is 2 weeks from the moment it is received. Or SignOut for early expiration. Not needed for the next request.
uid A unique value identifying the user. In our case, email.
token-type The type of token used.

An example request using the token from the previous response:

curl -i --header "access-token: tgervk9_9xicJYpmSsnnNA" \
 --header "token-type: Bearer" \
 --header "client: D-Uv3ER53873olhnNLjL9w" \
 --header "uid: api@local.net" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"page":"2"}' \
 https://uztgs.uz/api/v1/stations

In response we will receive the following message:

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: Bmh2GVrxr6aW0Hngor4gPw
token-type: Bearer
client: D-Uv3ER53873olhnNLjL9w
expiry: 1615311367
uid: api@local.net
ETag: W/"ba0df406b647bd92f0bf3a18916714c1"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 35a26441-ae78-48fa-8b2e-e92d2605133b
X-Runtime: 0.167748
Transfer-Encoding: chunked
{"data": [
{"id":1,"name":"865293041101853","equipment_brand_name":"Corrector BK","phone":"","equipment_id":1},...
 ],
"total_pages":7,
"current_page":2
}

To complete the work, you can use the SignOut procedure, or save the necessary headers from the last request and, if the token lifetime has not expired, use them next time.

Warning

Please remember that without terminating the session, the last token will be valid for two weeks.

Ending a session:

curl -i --header "access-token: Bmh2GVrxr6aW0Hngor4gPw" \
 --header "token-type: Bearer" \
 --header "client: D-Uv3ER53873olhnNLjL9w" \
 --header "uid: api@local.net" \
 --request DELETE \
 https://uztgs.uz/api/v1/auth/sign_out
HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
ETag: W/"c955e57777ec0d73639dca6748560d00"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: b4b69ac3-5cba-4e6e-b6a0-f6577298c166
X-Runtime: 0.141467
Transfer-Encoding: chunked
{"success":true}

Description of views

Consumers view

The Consumers view returns a paged list of the resource provider’s consumers.

Resource ID:

https://uztgs.uz/api/v1/customers?page=1

Input parameters:

  • page="page number" - page number.

Return data:

{"data":[
       {
        "id":13,
        "name":"O'ZBEKISTON YENGIL ATLETIKA FEDERATSIYASI",
        "subdivision_type_name":"User",
        "inn":"0204875446",
        "contact_number":"+998-91-381-18-88"
}, ..., {
         "id":22,
          "name":"\"TRANSYO`LQURILISH\" DUK",
          "subdivision_type_name":"User",
          "inn":"0300943875",
          "contact_number":"+998-97-354-54-01"
} ],
  "total_pages":8,
  "current_page":2,
  "next_page":3
}

Description of view parameters:

Attribute name Description
id Identifier (unique key) of the consumer in the system
name Consumer name
subdivision_type_name Consumer type
inn Tax identification number
contact_number Contact number
data Array of returned data
total_pages Total number of pages in the returned set
current_page Current page
next_page Next page available for downloading, null if the current page is the last one

Metering Units View

The Metering Units view returns a paged list of the resource provider’s metering units.

Resource ID:

https://uztgs.uz/api/v1/stations?page=1

Input parameters:

  • page="page number" - page number.

Return data:

{"data":[
{
"id":18,
        "name":"LLC \"Coca-Cola Ichimligi Uzbekistan\" LTD",
        "equipment_type_id":1,
        "equipment_brand_name":"BK",
        "phone":"+998-97-725-12-28",
        "equipment_id":61,
        "customer_id":14
    }
... ],
  "total_pages":9,
  "current_page":2,
  "next_page":3
}

Description of view parameters:

Attribute name Description
id Identifier (unique key) of the metering unit in the system
name Name of the metering unit
equipment_type_id Identifier of the configuration type of the metering device (key of the configuration type of the corrector)
equipment_brand_name Model of the metering device
phone Phone
equipment_id Identifier (unique key) of the metering device in the system
customer_id Consumer identifier
data Array of returned data
total_pages Total number of pages in the returned set
current_page Current page
next_page Next page available for downloading, null if the current page is the last one

Readings Archives view

General view

The “Readings Archives” view returns a list of metering unit readings broken down by archive type and resource provider time interval.

Resource ID:

https://uztgs.uz/api/v1/channel_data?archive_type=hourly&equipment_id=25&fp_end=2021-02-20&fp_start=2021-02-01&page=2

Input parameters:

  • archive_type="archive type" - archive type for which data is being uploaded. For a list of archive types, see the table “Directory of archive types”;
  • equipment_id="metering device identifier" - metering device identifier for which data is being uploaded;
  • fp_start="yyyy-mm-dd" - time interval (segment start) in yyyy-mm-dd format for which data is being uploaded;
  • fp_end="yyyy-mm-dd" - time interval (segment end) in yyyy-mm-dd format for which data is being uploaded;
  • page="page number" - page number.

Return data:

{
"data": [
   {
     "event_time": 1612292400,
     "channel_data": [
       { "T": 25.193481 },
       { "VNakpriv": 89519.01 },
       { "VNakwork": 292537.06 },
       { "P": 0.9954071 }
] },
...,
   {
     "event_time": 1612288800,
     "channel_data": [
       { "P": 0.995224 },
       { "VNakpriv": 89519.01 },
       { "VNakwork": 292537.06 },
       { "T": 25.103271 }
] }
],
 "total_pages": 2,
 "current_page": 1,
 "next_page": 2
}

Description of view parameters:

Attribute name Description
event_time Date and time of meter readings in UTC format
channel_data Archive data. The data depends on the parameters archive type and metering device corrector type. For a description of the parameter channels, see the table “Directory of metering unit channel parameters”
data Array of returned data
total_pages Total number of pages in the returned set
current_page Current page
next_page Next page available for downloading, null if the current page is the last one

Unified view

The view returns a list of metering unit readings by archive type and resource provider time interval in a unified form.

Resource ID:

https://uztgs.uz/api/v1/channel_data?archive_type=hourly&equipment_id=25&fp_end=2021-02-20&fp_start=2021-02-01&page=2& channel_consolidation=1

Input parameters:

  • archive_type="archive type" - archive type for which data is being uploaded. For a list of archive types, see the table “Directory of archive types”;
  • equipment_id="metering device identifier" - metering device identifier for which data is being uploaded;
  • fp_start="yyyy-mm-dd" - time interval (segment start) in yyyy-mm-dd format for which data is being uploaded;
  • fp_end="yyyy-mm-dd" - time interval (segment end) in yyyy-mm-dd format for which data is being uploaded;
  • page="page number" - page number.
  • "channel_consolidation": “1” unloading parameter in a unified form, if any.

Returning data in a unified form, if the "channel_consolidation": "1" parameter is present:

{
"data":[
             {"event_time":1631791097,
             "channel_data":[
                    {"gas_consume":"503.2795"},
                    {"reading_value":"671893.9226"},
                    {"VNakwork":"15402.9101"},
                    {"Vwork":"15398"},
                    {"P":"1.4"},
                    {"T":"20"}]}],
       "total_pages":1,
       "current_page":1,
       "next_page":null
}

Description of view parameters:

Attribute name Description
event_time Date and time of meter readings in UTC format
channel_data Archive data. Unified channel names: gas_consume - standard gas volume for the period, reading_value - accumulated standard gas volume, VNakwork - accumulated working gas volume, Vwork - working gas volume, P - pressure, T - temperature
data Array of returned data
total_pages Total number of pages in the returned set
current_page Current page
next_page Next page available for downloading, null if the current page is the last

Directories

When unloading data, you must use the following directories.

Directory of archive types

Archive name Archive code (identifier) ​​
Hourly archive of readings hourly
Daily archive of readings daily
Monthly archive of readings monthly
Annual archive of readings yearly
Archive of emergency situations nesht

Directory of metering unit channel parameters

Device type ID Corrector type Archive type Channel name Channel code Unit of measurement
number equipment_type_id corrector_name archive_type channel_name channel_varname unit_name
1 1 BK monthly working volume Vwork m3
2 1 BK monthly reduced volume Vpriv m3
3 1 BK monthly accumulated working volume Vnakwork m3
4 1 BK monthly accumulated reduced volume Vnakpriv m3
5 1 BK daily pressure P kgs/cm2
6 1 BK daily temperature T °C
7 1 BK daily working volume Vwork m3
8 1 BK daily reduced volume Vpriv m3
9 1 BK daily accumulated working volume Vnakwork m3
10 1 BK daily accumulated reduced volume Vnakpriv m3
11 1 BK hourly pressure P kgs/cm2
12 1 BK hourly temperature T °C
13 1 BK hourly accumulated working volume Vnakwork m3
14 1 BK hourly accumulated reduced volume Vnakpriv m3
15 2 Flowgas monthly total accumulated volume RU Vwork m3
16 2 Flowgas monthly total accumulated volume SU Vst m3
17 2 Flowgas monthly accumulated volume RU Vnakwork m3
18 2 Flowgas monthly accumulated volume SU Vnakst m3
19 2 Flowgas daily average pressure P kPa
20 2 Flowgas daily average temperature T °C
21 2 Flowgas daily total accumulated volume RU Vwork m3
22 2 Flowgas daily total accumulated volume SU Vst m3
23 2 Flowgas daily accumulated volume RU Vnakwork m3
24 2 Flowgas daily accumulated volume SU Vnakst m3
25 2 Flowgas hourly average pressure P kPa
26 2 Flowgas hourly average temperature T °C
27 2 Flowgas hourly total accumulated volume RU Vwork m3
28 2 Flowgas hourly total accumulated volume SU Vst m3

To obtain the above table “Directory of channels-parameters of the metering node”, you need to use the resource described in the section View “Channels”

Meter Types View

The Meter Types view returns a paged list of meter types.

Resource ID:

https://uztgs.uz/api/v1/equipment_types?page=1

Input parameters:

  • page="page number" - page number

Return data:

{
"data":[
{
"id":1,
         "name":"BK",
         "equipment_kind_name":"Corrector",
         "telemetry_type_name":"vdTel-1",
         "resource_name":"Gas",
         "description":"Gas volume corrector BK"
} ],
   "total_pages":1,
   "current_page":1,
   "next_page":`null`
}

Description of view parameters:

Attribute name Description
id Identifier (unique key) of the consumer in the system
name Name of the metering device type
equipment_kind_name Name of the metering device type
telemetry_type_name Name of the telemetry type
resource_name Energy resource
description Description
total_pages Total number of pages in the returned set
current_page Current page
next_page Next page available for downloading, null if the current page is the last

Channels View

The Channels view returns a paged list of channels linked to a meter type.

Resource ID:

https://uztgs.uz/api/v1/channel_archive_types?equipment_type_id=25&page=1

Input parameters:

  • equipment_type_id= «metering device configuration type identifier» - identifier of the metering device configuration type, according to which channels are unloaded;
  • page=«page number» - page number.

Return data:

{
"data":[
      {
         "equipment_type_id":2,
         "archive_type_name":"Daily readings archive",
         "archive_type_varname":"daily",
         "channel_name":"Average pressure",
         "channel_varname":"P",
         "unit_name":"kPа"
} ],
   "total_pages":4,
   "current_page":1,
   "next_page":2
}

Description of view parameters:

Attribute name Description
equipment_type_id Identifier of the metering device configuration type (unique key) in the system
archive_type_name Archive type name
archive_type_varname Archive type code
telemetry_type_name Telemetry type name
channel_name Channel name
channel_varname Channel code
unit_name Unit of measurement
total_pages Total number of pages in the returned set
current_page Current page
next_page Next page available for downloading, null if the current page is the last one

Configuration View

The Configuration view returns a paged list of the meter configuration.

Resource ID:

https://uztgs.uz/api/v1/channel_data?archive_type=settings&equipment_id=25&page=1

Input parameters:

  • archive_type="archive type" - archive type, for configuration it is “settings”;
  • equipment_id="metering device identifier" - metering device identifier for which data is being uploaded;
  • page="page number" - page number.

Returning data:

{
"data":[
      {
         "channel_name":"Presence of ambient temperature sensor
(1 – sensor installed, 0 – sensor absent)",
         "channel_data_value":"0",
         "unit_name":null
      },
   ],
   "total_pages":1,
   "current_page":1,
   "next_page":null
}

Description of view parameters:

Attribute name Description
channel_name Configuration name
channel_data_value Configuration value
unit_name Unit of measurement
total_pages Total number of pages in the returned set
current_page Current page
next_page Next page available for downloading, null if the current page is the last one

Last session date

The view returns the last session date.

Resource ID:

https://uztgs.uz/api/v1/stations/last_seance_event_time?id=2018

Input parameters:

  • id= «metering unit identifier»

Return data:

{
  "data":{
   "station_name":"station 3 type j",
   "last_seance_event_time":1674713405}
}

Description of view parameters:

Attribute name Description
station_name Metering unit name
last_seance_event_time Date and time of the last communication session of the metering unit in the format

Data upload procedure

Initial authentication

Warning

When unloading data, a correctly prepared request with correctly specified input parameters is important. The request header must contain header "Content-Type: application/json" (an example of a call is described in detail in the “Authentication” subsection))

Initial authentication is described in the Authentication subsection.

For initial authentication, the email and password of an existing user are used. To do this, you need to send a POST request, for example:

curl -i --header "Content-Type: application/json" \
     --request POST \
     --data '{"email":"user@local.net","password":"Str0ngPas$"}' \
     https://uztgs.uz/api/v1/auth/sign_in

Unloading a list of consumers

To unload a list of consumers, you need to send a POST request, for example:

curl -i --header "access-token: *********************" \
 --header "token-type: Bearer" \
 --header "client: **********************" \
 --header "uid: user@local.net" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"page":"2"}' \
 https://uztgs.uz/api/v1/customers

Data is downloaded page by page ("total_pages": 7 - total number of pages, "current_page": 1 - current page).

It is necessary to organize cyclical downloading of data by page number:

{"data":[
       {
        "id":13,
        "name":"O'ZBEKISTON YENGIL ATLETIKA FEDERATSIYASI",
        "subdivision_type_name":"Unit Owner",
        "inn":"0204875446",
        "contact_number":"+998-91-381-18-88"
},
... ],
  "total_pages":8,
  "current_page":2,
  "next_page":3
}

For further data download ( downloading of value archives) we will need the following parameters:

  • ``“id”: 13 (“customer_id”: “13”`) - identifier (unique key) of the consumer in the system.

Downloading the list of metering units

To upload the list of metering nodes you should send a POST request, for example:

curl -i --header "access-token: *********************" \
 --header "token-type: Bearer" \
 --header "client: **********************" \
 --header "uid: user@local.net" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"page":"2"}' \
 https://uztgs.uz/api/v1/stations

Data is downloaded page by page (“total_pages”: 7 - total number of pages,“current_page”: 1 - current page).

It is necessary to organize cyclic data download by page number.

{"data":[
{
"id":18,
        "name":"ООО \"Coca-Cola Ichimligi Uzbekistan\" LTD",
        "equipment_type_id":1,
        "equipment_brand_name":"BK",
        "phone":"+998-97-725-12-28",
        "equipment_id":61,
        "customer_id":14
    }
... ],
  "total_pages":9,
  "current_page":2,
  "next_page":3
}

For further data download ( downloading archives of values) we need the following parameters:

  • ``equipment_id’’: 61`-identifier of the metering device.

For data harmonization (directories):

  • ``customer_id’’: 14`-customer identifier;
  • ``equipment_type_id'': 61 - identifier of the configuration type of the metering device.

Downloading metering device types

To download metering device types you should send a POST request, for example:

curl -i  --header "access-token: *********************" \
 --header "token-type: Bearer" \
 --header "client: **********************" \
 --header "uid: user@local.net" \
 --request GET \
--header "Content-Type: application/json"  \
--data '{"page":"1"}' \
 https://uztgs.uz/api/v1/equipment_types

It is necessary to organize cyclic data download by the following parameters:

  • page - page number.

Channels download

To download channels with binding to the type of metering device you should send a POST request, for example:

curl -i  --header "access-token: *********************" \
 --header "token-type: Bearer" \
 --header "client: **********************" \
 --header "uid: user@local.net" \
 --request GET \
--header "Content-Type: application/json"  \
--data '{"equipment_type_id": "2", "page":"1"}' \
 https://uztgs.uz/api/v1/channel_archive_types

It is necessary to organize cyclic data downloading by the following parameters:

  • equipment_type_id - identifier of the device configuration type;
  • page - page number.

Downloading of readings archives

To download archives of readings it is necessary to send a POST request, for example:

curl -i --header "access-token: *********************" \
 --header "token-type: Bearer" \
 --header "client: **********************" \
 --header "uid: user@local.net" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"archive_type": "hourly", "equipment_id":"25",  "fp_
end":"2021-02-20", "fp_start":"2021-02-01", "page":"1"}' \
 https://uztgs.uz/api/v1/channel_data

It is necessary to organize cyclic data downloading by the following parameters:

  • equipment_id - identifier of the metering device;
  • archive_type - archive type (see the reference book);
  • fp_start - start of time interval;
  • fp_end - end of time interval;
  • page - page number.

Downloading the archive for a period

To download the archive for a period you should send a POST request, for example:

curl -i --header "access-token: *********************" \
 --header "token-type: Bearer" \
 --header "client: **********************" \
 --header "uid: user@local.net" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"archive_type": "hourly", "equipment_id":"25",  "fp_
end":"2021-02-20", "fp_start":"2021-02-01", "page":"1", "channel_
consolidation": "1"}' \
 https://uztgs.uz/api/v1/channel_data

It is necessary to organize cyclic data download by the following parameters:

  • equipment_id - identifier of the metering device;
  • archive_type - archive type (see the reference book);
  • fp_start - start of time interval;
  • fp_end - end of time interval;
  • page - page number;
  • channel_consolidation: 1 - unified upload parameter.

Downloading the configuration of the meter

To download the meter configuration you should send a POST request, for example:

curl -i --header "access-token: *********************" \
 --header "token-type: Bearer" \
 --header "client: **********************" \
 --header "uid: user@local.net" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"archive_type": "settings", "equipment_id":"25",
"page":"1"}' \
 https://uztgs.uz/api/v1/channel_data

It is necessary to organize cyclic data download by the following parameters:

  • equipment_id - identifier of the metering device;
  • archive_type = “settings”;
  • page - page number.

Downloading the date of the last communication session

To upload the date of the last communication session of the metering unit you should send a POST request, for example:

curl -i --header "access-token: *********************" \
--header "token-type: Bearer" \
--header "client: **********************" \
 --header "uid: user@local.net" \
 --request GET  \
--header "Content-Type: application/json" \
--data '{ "id": "1816"}' https://uztgs.uz/api/v1/stations/last_seance_
event_time

It is necessary to organize data download by parameter:

  • id - identifier of the metering node.

Note

After performing steps 1 - 9, it is necessary to end the session.

Zuletzt aktualisiert am