This API includes sensors’ positioning, grouping and zoning attributes so that your data receiving service can be stateless.

General Info

The API can be used with all types of parking lots: marked spaces, open bays, off-street parking and garages.

Please, watch the video at the end of this document to learn how to set up RabbitMQ Endpoint in the Nwave Console.

Features

Parking session correction is the most important functionality of Parking Session Logging API 2.0. The wireless data reception is not perfect, so some messages may be lost. To minimize this effect, Nwave recommends to use at least 2 stations in the same area, but message loss is still possible. Nwave Cloud analyzes additional data from parking sensors and recovers most of the lost messages. When a message is recovered, the Nwave Cloud analyzes occupancy history and makes a correction. It may correct the session’s start or end time as well as create new parking sessions.

Another feature is the addition of error start and end time. When 2 consecutive messages are lost, the Cloud cannot make a high-quality session correction, but to minimize negative effect Nwave has added delta_time_sec field. This field represents the maximum deviation in seconds from event time. This way, our API users can have information about sessions that are definitely correct and sessions that possibly had a time error and the duration of that error. This is useful in systems which generate data for parking enforcement applications - an inspector can be directed only to parking lots where cars are parked too long.

API details

Data objects

Every parking session is described by the following data structure:

...

API details

Data objects

Every parking session is described by the following data structure:

Code Block

language	json

{
    "parking_session_uuid": "string",
    "correction_counter": integer,
    "session_start":{
        "event_time": "string" // timestamptz, yyyy-MM-dd'T'HH:mm:ss.SSSXXX (2019-06-13T16:16:51.000+00:00)
        "delta_time_sec": integer,
        "message_trace_ids":["strings""]
    },
    "partial_end":{
        "event_time": "string" // timestamptz, yyyy-MM-dd'T'HH:mm:ss.SSSXXX (2019-06-13T16:16:51.000+00:00)
        "delta_time_sec": "integer",
        "message_trace_ids":["strings"],
        "network_id": "string", // unexpectedly released position
        "custom_id": "string"
    },
    "session_startend":{
        "event_time": "string" // timestamptz, yyyy-MM-dd'T'HH:mm:ss.SSSXXX (2019-06-13T16:16:51.000+00:00)
        "delta_time_sec": integer,
        "message_trace_ids":["strings"]
    },
    "partialinvolved_enddevices":{[
        {
 "event_time":string // timestamptz, yyyy-MM-dd'T'HH:mm:ss.SSSXXX (2019-06-13T16:16:51.000+00:00)         "deltaserial_time_secid":integer "string", # deprecated
      "message_trace_ids":[strings],
        "networkdevice_id": "string",
//  unexpectedly released position         "customhardware_idtype": "string",
      },       "session_endposition":{
         "event_time":string // timestamptz, yyyy-MM-dd'T'HH:mm:ss.SSSXXX (2019-06-13T16:16:51.000+00:00)        "network_id": "string",
                 "deltacustom_time_secid":integer "string",
        "message_trace_ids":[strings]     },     "involved_deviceslatitude":[ float,
       {              "serial_id"longitude":string float,
#   deprecated              "device_idgroup":{
 string,              "hardware_type      "id":string, int,
                     "positiontype":{ "string",
                     "network_idname": "string",
                     "custom_id": "string",
                 "latitude    "zone_id":float int,
                 "longitude    "level_id":float int,
                 "group":{    "level_name": "string",
                     "idfloor_number": int,
                     "type":string},
                     "name"group_inner_id":string,
    int,
                 "custom_idlabels":["string,"]
            }
        "zone_id":int},
        ...
    ],
       "level_id"auth_ble_tag": int,{
        "tag_id": "string",
           "levelevent_nametime": str,"string"
    },
       "auth_mobile": {
        "floorsession_numberid": int"string",
        "event_time": "string"
       },
                 "group_inner_id":int,}
}

Objects description

parking_session_uuid - a unique parking session-id;

correction_counter - total number of corrections.

...

Code Block

language	json

"session_start":{
    "event_time":string //       }
        },
        ...timestamptz, yyyy-MM-dd'T'HH:mm:ss.SSSXXX (2019-06-13T16:16:51.000+00:00)
    ]"delta_time_sec":integer,
    "authmessage_bletrace_tagids": {
        "tag_id": str,
        "event_time": string
    },
    "auth_mobile": {
        "session_id": string,
        [strings]
}

The object session_startis sent to open a parking occupancy session:

event_time - a session start timestamp;

delta_time_sec - an error of session start time in seconds;

message_trace_ids - tracing identifiers of raw device messages related to the session start

...

Code Block

language	json

"session_end":{
    "event_time": string //    }
}

Objects description

parking_session_uuid - a unique parking session-id;

correction_counter - total number of corrections.

Code Block
"session_start":{ "event_time":string // timestamptz, yyyy-MM-timestamptz, yyyy-MM-dd'T'HH:mm:ss.SSSXXX (2019-06-13T16:16:51.000+00:00) "delta_time_sec":integer, "message_trace_ids":[strings] }

The object session_startend is sent to open close a parking occupancy session:

event_time - a session start end timestamp;

delta_time_sec - an error of session start end time in seconds;

message_trace_ids - tracing identifiers of raw device messages related to the session startend.

...

Code Block

language	json

"sessionpartial_end":{
    "event_time":string // timestamptz, yyyy-MM-dd'T'HH:mm:ss.SSSXXX (2019-06-13T16:16:51.000+00:00)
    "delta_time_sec":integer,
    "message_trace_ids":[strings],
    "network_id":string,
    "custom_id":string
}

The object session_end is sent to close a parking occupancy session:

event_time - a session end timestamppartial_end object can be received only for Open Bay parking type

A partial end is an event where two sensors were occupied in an open bay session but only one sensor was released. This is a temporary state of parking sessions. A session_end object will always be sent when the second sensor is released in that session.

event_time - a timestamp of unexpected sensor release;

delta_time_sec - an error of session end time a timestamp error in seconds;

message_trace_ids - tracing identifiers of raw device related to the session endmessages which describe unexpected release;

network_id - network_id of a sensor’s position that was unexpectedly released;

custom_id- a user-defined identifier of a sensor’s position that was unexpectedly released.

...

Code Block

language	json

"partialinvolved_enddevices":[
  {
        "eventserial_timeid":string // timestamptz, yyyy-MM-dd'T'HH:mm:ss.SSSXXX (2019-06-13T16:16:51.000+00:00),, # deprecated
         "deltadevice_time_secid":integer string,
    "message_trace_ids":[strings],     "networkhardware_idtype":string,
    "custom_id    "position":string
}

partial_end object can be received only for Open Bay parking type

A partial end is an event where two sensors were occupied in an open bay session but only one sensor was released. This is a temporary state of parking sessions. A session_end object will always be sent when the second sensor is released in that session.

event_time - a timestamp of unexpected sensor release;

delta_time_sec - a timestamp error in seconds;

message_trace_ids - tracing identifiers of messages which describe unexpected release;

network_id - network_id of a sensor’s position that was unexpectedly released;

custom_id- a user-defined identifier of a sensor’s position that was unexpectedly released.

Code Block

"involved_devices":[
  {{
            "network_id":string,
            "custom_id":string,
            "latitude":float,
            "longitude":float,
            "group":{
                "id":int,
                "type":string,
                "name":string,
                "custom_id":string,
                "zone_id":int,
                "level_id": int,
                "level_name": str,
                "floor_number": int
            },
            "group_inner_id":int,
            "labels":["string"]
        }
    },
    ...
]

involved_devices - a list which contains a description of parking sensors involved in a parking session;

serial_id - a parking sensor serial ID (deprecated);

device_id - a parking sensor serial ID;

hardware_type - a parking sensor hardware model;

position.network_id - a position network_id;

position.custom_id- a position user-defined identifier;

position.latitude/longitude - a position geolocation coordinates;

position.group.id- a position group ID;

position.group.type - a position group type. Possible values: general, unmarked_parking_bay, marked_parking_bay;

position.group.name - a position group name;

position.group.custom_id - a position group user-defined ID;

position.group.zone_id - an ID of a zone which contains positions group;

position.group.level_id - an ID of level (floor) which contains positions group;

position.group.level_name - a Name of level (floor) which contains positions group;

position.group.floor_number - a floor number which contains positions group;

position.group_inner_id - an index number of a position in positions group;

position.labels - list of position labels

...

Code Block

language	json

"auth_ble_tag": {
    "tag_id": str,
    "event_time": string
}

The object auth_ble_tag contains user authorization information if a user authorized on parking space using Nwave’s BLE-Tag;

tag_id - ID of BLE-Tag;

event_time- a timestamp of user authorization.

...

Code Block

language	json

"auth_mobile": {
    "session_id": string,
    "event_time": string
}

The object auth_mobilecontains user authorization information if a user authorized on a parking space using mobile application connected to the Nwave One-Click Check-in service;

one_click_session_id - an ID of One-Click Check-in session;

event_time- a timestamp of user authorization.

Examples

Session start message

When a parking session starts, the Nwave cloud builds a message that contains only data about the sensor and time of parking session beginning.

It can contain one or two described devices depending on the device’s group type.

Code Block

language	json

 {
  "parking_session_uuid": "e9fcc95e-b9cd-4e7f-b275-092a62daf61d",
  "involved_devices": [
    {
      "device_id": "a33b47",
      "hardware_type": "Sparkit Surface V3.9",
      "position": {
        "network_id": "23f3e949-2dd3-47ca-b00f-c3310d4ce418",
        "custom_id": "684d395c-e875-422a-904d-c095ad981cc6",
        "latitude": 50.793682,
        "longitude": -1.0986286,
        "group": {
          "id": 1545,
          "type": "unmarked_parking_bay",
          "name": "cambridgepark32",
          "custom_id": "684d395c-e875-422a-904d-c095ad981cc6",
          "zone_id": 5,
          "level_id": null,
          "floor_number": null
        },
        "group_inner_id": 1,
        "labels": ["my label"]
      }
    }
  ],
  "correction_counter": 0,
  "session_start": {
    "event_time": "2021-01-26T07:48:40.121000+00:00",
    "delta_time_sec": 60,
    "message_trace_ids":
    [
      "d1b6d450-cc5f-83d4-adbe-c9f5383fb0d8"
    ]
  }
}

as you can see, the value of field delta_time_sec is 60. It means, that real parking session start time is between 2021-01-26T07:48:40 - 60 sec and 2021-01-26T07:48:40 + 60 sec.

Session end message

Code Block

language	json

{
  "parking_session_uuid": "e9fcc95e-b9cd-4e7f-b275-092a62daf61d",
  "involved_devices": [
    {
      "device_id": "a33b47",
      "hardware_type": "Sparkit Surface V3.9",
      "position": {
        "network_id": "23f3e949-2dd3-47ca-b00f-c3310d4ce418",
        "custom_id": "684d395c-e875-422a-904d-c095ad981cc6",
        "latitude": 50.793682,
        "longitude": -1.0986286,
        "group": {
          "id": 1545,
          "type": "unmarked_parking_bay",
          "name": "cambridgepark32",
          "custom_id": "684d395c-e875-422a-904d-c095ad981cc6",
          "zone_id": 5,
          "level_id": null,
          "floor_number": null
        },
        "group_inner_id": 1,
        "labels": ["my label"]
      }
    }
  ],
  "correction_counter": 0,
  "session_start": {
    "event_time": "2021-01-26T07:48:40.121000+00:00",
    "delta_time_sec": 60,
    "message_trace_ids": [
      "d1b6d450-cc5f-83d4-adbe-c9f5383fb0d8"
    ]
  },
  "session_end": {
    "event_time": "2021-01-26T07:51:26.466000+00:00",
    "delta_time_sec": 0,
    "message_trace_ids": [
      "06f75246-20e5-9d48-404b-fa965bbdefe7"
    ]
  }
}

Partial-end message

Partial-end is possible only for unmarked group type when a car parks on 2 neighbouring sensors. When a car releases only a single sensor, the partial-end message is sent. When the car releases the second sensor, the session end message is sent. This event can happen when a car tries to join traffic on a busy road.

Here we show an example of the partial-end message:

Code Block

language	json

{
  "parking_session_uuid": "da2ecb68-efb1-458e-ba5d-e5ba80b87f6e",
  "involved_devices": [
    {
      "device_id": "33c83",
      "hardware_type": "Sparkit Surface V3.9",
      "position": {
        "network_id": "00000000-0000-0000-0000-000000033c83",
        "custom_id": "cd4206ec-6876-4eca-b859-d5735dd97386",
        "latitude": 50.780323,
        "longitude": -1.0682689,
        "group": {
          "id": 1729,
          "type": "unmarked_parking_bay",
          "name": "5EastneyEsplanade",
          "custom_id": "cd4206ec-6876-4eca-b859-d5735dd97386",
          "zone_id": 5,
          "level_id": null,
          "floor_number": null
        },
        "group_inner_id": 54
      }
    }, {
      "device_id": "33e5f",
      "hardware_type": "Sparkit Surface V3.9",
      "position": {
        "network_id": "00000000-0000-0000-0000-000000033e5f",
        "custom_id": "cd4206ec-6876-4eca-b859-d5735dd97386",
        "latitude": 50.78033,
        "longitude": -1.0682275,
        "group": {
          "id": 1729,
          "type": "unmarked_parking_bay",
          "name": "5EastneyEsplanade",
          "custom_id": "cd4206ec-6876-4eca-b859-d5735dd97386",
          "zone_id": 5,
          "level_id": null,
          "floor_number": null
        },
        "group_inner_id": 55
      }
    }
  ],
  "correction_counter": 0,
  "session_start": {
    "event_time": "2021-01-26T09:54:08.287000+00:00",
    "delta_time_sec": 0,
    "message_trace_ids": [
      "65ab2a63-e7c2-8674-aa3d-7047cb428a31"
    ]
  },
  "partial_end": {
    "event_time": "2021-01-26T10:03:23.900000+00:00",
    "delta_time_sec": 0,
    "message_trace_ids": [
      "56d9035a-e4dc-9661-0804-a968d9a92d0b"
    ],
    "network_id": "00000000-0000-0000-0000-000000033e5f",
    "custom_id": "cd4206ec-6876-4eca-b859-d5735dd97386"
  }
}

In the example above you can see that object “partial-end” contains only one sensor.

When the second sensor in the session is released, the Nwave cloud will add a “session-end” object to the end of the partial-end message.

Expand

Code Block

language	json

 {
  "parking_session_uuid": "da2ecb68-efb1-458e-ba5d-e5ba80b87f6e",
  "involved_devices": [
    {
      "device_id": "33c83",
      "hardware_type": "Sparkit Surface V3.9",
      "position": {
        "network_id": "00000000-0000-0000-0000-000000033c83",
        "custom_id": "cd4206ec-6876-4eca-b859-d5735dd97386",
        "latitude": 50.780323,
        "longitude": -1.0682689,
        "group": {
          "id": 1729,
          "type": "unmarked_parking_bay",
          "name": "5EastneyEsplanade",
          "custom_id": "cd4206ec-6876-4eca-b859-d5735dd97386",
          "zone_id": 5,
          "level_id": null,
          "floor_number": null
        },
        "group_inner_id": 54
      }
    }, {
      "device_id": "33e5f",
      "hardware_type": "Sparkit Surface V3.9",
      "position": {
        "network_id": "00000000-0000-0000-0000-000000033e5f",
        "custom_id": "cd4206ec-6876-4eca-b859-d5735dd97386",
        "latitude": 50.78033,
        "longitude": -1.0682275,
        "group": {
          "id": 1729,
          "type": "unmarked_parking_bay",
          "name": "5EastneyEsplanade",
          "custom_id": "cd4206ec-6876-4eca-b859-d5735dd97386",
          "zone_id": 5,
          "

serial

level_id":

string

 null,

,

#

deprecated

device

floor_

id

number":

string

 null
        },
        "

hardware

group_inner_

type

id":

string

 55
      }
    }
  ],
  "correction_counter": 0,

position

session_start": {

"event_time": "2021-01-26T09:54:08.287000+00:00",

network

delta_time_

id

sec":

string

 0,
    "message_trace_ids": [
      "

custom_id":string,

65ab2a63-e7c2-8674-aa3d-7047cb428a31"
    ]
  },
  "

latitude

partial_end":

float,

"event_time": "2021-01-26T10:03:23.900000+00:00",
    "

longitude

delta_time_sec":

float

 0,
    "message_trace_ids": [
      "

group":{

56d9035a-e4dc-9661-0804-a968d9a92d0b"
    ],

"network_id":

int

 "00000000-0000-0000-0000-000000033e5f",
    "custom_id": "cd4206ec-6876-4eca-b859-d5735dd97386"
  },
  "session_end": {
    "

type

event_time":

string,

 "2021-01-26T10:16:10.116000+00:00",
    "delta_time_sec": 0,

"name

"message_trace_ids":

string,

 [
      "8182f7b8-f5bf-2084-aac8-0b3412965a84"
    ]

"custom_id":string, "zone_id":int, "level_id": int, "level_name": str, "floor_number": int }, "group_inner_id":int, } }, ... ]

involved_devices - a list which contains a description of parking sensors involved in a parking session;

serial_id - a parking sensor serial ID (deprecated);

device_id - a parking sensor serial ID;

hardware_type - a parking sensor hardware model;

position.network_id - a position network_id;

position.custom_id- a position user-defined identifier;

position.latitude/longitude - a position geolocation coordinates;

position.group.id- a position group ID;

position.group.type - a position group type. Possible values: general, unmarked_parking_bay, marked_parking_bay;

position.group.name - a position group name;

position.group.custom_id - a position group user-defined ID;

position.group.zone_id - an ID of a zone which contains positions group;

position.group.level_id - an ID of level (floor) which contains positions group;

position.group.level_name - a Name of level (floor) which contains positions group;

position.group.floor_number - a floor number which contains positions group;

position.group_inner_id - an index number of a position in positions group.

Code Block

"auth_ble_tag": { "tag_id": str,

}
}

Session edges correction

As you can see in the examples above, all the messages contain the correction_counter field. This field and the field parking_session_uuid allows you to apply corrections to parking sessions in the right order.

Parking session correction is an important functionality of Parking Session Logging API. The wireless data reception is not ideal, so some messages may be lost. To minimize this effect, Nwave recommends to use at least 2 stations in the same area, but message loss is still possible. Nwave Cloud analyzes additional data from parking sensors and recovers most of the lost messages. When a message is recovered, the Nwave Cloud analyzes occupancy history and makes a correction. It may correct the session’s start or end time as well as create new parking sessions.

For example, let’s consider 2 messages describing the parking session starting:

Code Block

language	json

{
  "parking_session_uuid": "da2ecb68-efb1-458e-ba5d-e5ba80b87f6e",
  "involved_devices": [
    {
      ...
    }
  ],
  "correction_counter": 0,
  "session_start": {
    "event_time": "2021-01-26T09:54:08.287000+00:00",
    "delta_time_sec": 120,
    "message_trace_ids": [
      "65ab2a63-e7c2-8674-aa3d-7047cb428a31"
    ]
  },
  ...
}

The message above contains the session_start object with delta_time_sec field equal to 0 and correction_counter field equal to 0. The following message corrects the previous one and decreases session start time delta.

Code Block

language	json

{
  "parking_session_uuid": "da2ecb68-efb1-458e-ba5d-e5ba80b87f6e",
  "involved_devices": [
    {
      ...
    }
  ],
  "correction_counter": 1,
  "session_start": {
    "event_time": string
}

The object auth_ble_tag contains user authorization information if a user authorized on parking space using Nwave’s BLE-Tag;

tag_id - ID of BLE-Tag;

event_time- a timestamp of user authorization.

Code Block
"auth_mobile": {"2021-01-26T09:55:32.944000+00:00", "delta_time_sec": 0, "sessionmessage_trace_idids": [ string, "event_time": string }

The object auth_mobilecontains user authorization information if a user authorized on a parking space using mobile application connected to the Nwave One-Click Check-in service;

one_click_session_id - an ID of One-Click Check-in session;

...

857e7628-38d4-4497-9229-c25d78096d52"
    ]
  },
  ...
}

As you can see, the correction message contains the same parking_session_uuid, incremented correction_counter and more accurate event_time. The second message contains different “message”trace_ids”

Endpoint & Route Setup

...

Versions Compared

Old Version 7

New Version Current

Key

General Info

Features

API details

Data objects

API details

Data objects

Objects description

Objects description

Examples

Session start message

Session end message

Partial-end message

Session edges correction

Endpoint & Route Setup

Page Comparison

Versions Compared

Old Version 7

New Version Current

Key

General Info

Features

API details

Data objects

API details

Data objects

Objects description

Objects description

Examples

Session start message

Session end message

Partial-end message

Session edges correction

Endpoint & Route Setup