The document describes methods and data formats used by Nwave's cloud-based API broker to relay preprocessed smart parking sensor events to the client's endpoints. The data can be passed with or without authorization.

Authorization Methods

Basic HTTP(s) Authentication using authorization header in the format of "Basic " + Base64 (username: password)
API-Key

Status Change

Event of sensor occupancy status change. Occupation detection time is 5-7 seconds and vacation detection time is 3-5 seconds.

Method: POST

Template Body:

{
  "message_type": "status_change",
  "message_trace_id": "{message_trace_id}",
  "occupied": "{"occupied" if parsed["occupation_status"] is True else "free"}",
  "parking_session_iterator": {parsed["parking_session_iterator"]},
  "previous_status_duration_min": {parsed["previous_occupancy_status_duration_min"]},
  "device_id": "{device_id}",
  "position":{
      "network_id": "{network_id}",
      "custom_id": "{custom_id}",
      "latitude": {latitude},
      "longitude": {longitude},
      "group_inner_id": {group_inner_id},
      "group":{
          "id": {group_id},
          "name": "{group_name}",
          "zone_id": {zone_id}
      }
  }
}

Example Message:

{
   "message_type":"status_change",
   "message_trace_id":"85e4c76a-c3f7-43fd-a1f4-2f85009e5751",
   "occupied":"occupied",
   "parking_session_iterator":2,
   "previous_status_duration_min":3,
   "device_id":"124244",
   "position":{
      "network_id":"00000000-0000-0000-0000-00000001e554",
      "custom_id":"",
      "latitude":51.49442797732277,
      "longitude":-0.1280093119192549,
      "group_inner_id":1,
      "group":{
         "id":4121,
         "name":"Test Group Delete After 26/02/2021",
         "zone_id":2779
      }
   }
}

message_trace_id - system message-id;
position_network_id - parking space network address;
new_status - parking occupancy status ("occupied" or "free");
previous_status_duration_min - duration of previous sensor status;
previous_status_duration_error_min - calculation error of the previous status duration;
session_iterator - short serial number of parking session. Iterator (number) is incrementing when new parking session starts (0-7);
latitude, longitude - GPS coordinates;
level - used for multi-level parking (0 for ground level parking);
zone_id - id of a device zone;
group_id - id of a parking bay;
group_name - name of a position group;
group_inner_id - a device number inside of a parking bay;
custom_id - a property "custom_id" of a position.

Template body

{
  "message_type": "status_change",
  "message_trace_id": "{message_trace_id}",
  "occupied": "{"occupied" if parsed["occupation_status"] is True else "free"}",,
  "parking_session_iterator": {parsed["parking_session_iterator"]},
  "previous_status_duration_min":{parsed["previous_occupancy_status_duration_min"]},
  "voltage_V": float,
  "device_id": "string",
  "position":{
      "network_id": "{network_id}",
      "custom_id": "{custom_id}",
      "latitude": {latitude},
      "longitude": {longitude},
      "group_inner_id": {group_inner_id},
      "group":{
          "id": {group_id},
          "name": "{group_name}",
          "zone_id": {zone_id},
          "custom_id": "{group_custom_id}"
      }
}

Heartbeat

The message is sent to confirm the health status of a sensor every 3 hours in case of unchanged occupancy status.

Method: PUT/POST

Body:

{
  "timestamp": "2019-10-01T18:59:11.254Z",
  "message_type": "heartbeat",
  "message_trace_id": "6c53ce93-27b3-40e4-b012-e4c3d3aea651",
  "message":
  {
    "position_network_id ": "6eb6d7d6-e486-45ff-a801-058765e2522a",
    "heartbeat_number": 3,
    "status": "free",
    "session_iterator": 1,
  },
  "location":
   {
     "latitude": -12.2334134,
     "longitude": 53.743789,
     "level": 3
   },
  "grouping":
   {
     "zone_id": 632,
     "group_id": 10365,
     "group_name": "Position group name",
     "group_inner_id": 16,
     "custom_id": "Position custom ID"
   }
}

message_trace_id - system message-id;
position_network_id - parking space network address;
heartbeat_number - the value increases for every following heartbeat during single occupancy state (0-11);
status - parking occupancy status ("occupied" or "free");
session_iterator - short number of parking session. Iterator is incrementing when parking session starts (0-7);
latitude, longitude - GPS coordinates;
level - used for multi-level parking (0 for ground level parking);
zone_id - id of a device zone;
group_id - id of a parking bay;
group_name - name of a position group;
group_inner_id - a device number inside of a parking bay;
custom_id - a property "custom_id" of a position.

Template body

{
  "timestamp": "{iso8601(message_time)}",
  "message_type": "heartbeat",
  "message_trace_id": "{message_trace_id}",
  "message":
  {
    "position_network_id": "{network_id}",
    "heartbeat_number": {parsed["heartbeat_message_counter"]},
    "status": "{"occupied" if parsed["occupation_status"] is True else "free"}",
    "session_iterator": {parsed["parking_session_iterator"]},
  },
  "location":
   {
     "latitude": {latitude},
     "longitude": {longitude},
     "level": {level}
   },
  "grouping":
   {
     "zone_id": {zone_id},
     "group_id": {group_id},
     "group_name": "{group_name}",
     "group_inner_id": {group_inner_id},
     "custom_id": "{custom_id}"
   }
}

User Registration (SDI Tag)

The message is sent to inform that a user has checked using an SDI tag.

Method: PUT/POST

Body:

{
  "timestamp": "2019-10-01T18:59:11.254Z",
  "message_type": "status_сhange",
  "message_trace_id": "6c53ce93-27b3-40e4-b012-e4c3d3aea651",
  "message":
   {
     "position_network_id": "6eb6d7d6-e486-45ff-a801-058765e2522a",
     "sdi_tag_id": "occupied",
     "previous_status_duration_min":36,
     "session_iterator": 1
   },
  "location":
   {
     "latitude": -12.2334134,
     "longitude": 53.743789,
     "level": 3
   },
  "grouping":
   {
     "zone_id": 632,
     "group_id": 10365,
     "group_name": "Position group name",
     "group_inner_id": 16,
     "custom_id": "Position custom ID"
   }
}

message_trace_id - system message-id;
position_network_id - parking space network address;
new_status - parking occupancy status ("occupied" or "free");
sdi_tag_id - an ID of Bluetooth tag which was used for authorization;
session_iterator - short serial number of parking session. Iterator (number) is incrementing when new parking session starts (0-7);
latitude, longitude - GPS coordinates;
level - used for multi-level parking (0 for ground level parking);
zone_id - id of a device zone;
group_id - id of a parking bay;
group_name - name of a position group;
group_inner_id - a device number inside of a parking bay;
custom_id - a property "custom_id" of a position.

Template body

{
  "timestamp": "{iso8601(message_time)}",
  "message_type": "status_сhange",
  "message_trace_id": "{message_trace_id}",
  "message":
   {
     "position_network_id": "{network_id}",
     "new_status": "{"occupied" if parsed["occupation_status"] is True else "free"}",
     "sdi_tag_id":{parsed["user_ID"]},
     "session_iterator": {parsed["parking_session_iterator"]}
   },
  "location":
   {
     "latitude": {latitude},
     "longitude": {longitude},
     "level": {level}
   },
  "grouping":
   {
     "zone_id": {zone_id},
     "group_id": {group_id},
     "group_name": "{group_name}",
     "group_inner_id": {group_inner_id},
     "custom_id": "{custom_id}"
   }
}

Standard Outgoing Protocol

Authorization Methods

Status Change

Heartbeat

User Registration (SDI Tag)