...
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:
| Code Block | ||
|---|---|---|
| ||
{
"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_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"]
},
"involved_devices":[
{
"serial_id": "string", # deprecated
"device_id": "string",
"hardware_type": "string",
"position":{
"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"string",
"floor_number": int
},
"group_inner_id":int, int,
"labels":["string"]
}
},
...
],
"auth_ble_tag": {
"tag_id": str"string",
"event_time": "string"
},
"auth_mobile": {
"session_id": "string",
"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-dd'T'HH:mm:ss.SSSXXX (2019-06-13T16:16:51.000+00:00)
"delta_time_sec":integer,
"message_trace_ids":[strings]
} |
...
message_trace_ids - tracing identifiers of raw device messages related to the session start
...
| Code Block | ||
|---|---|---|
| ||
"session_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]
} |
...
message_trace_ids - tracing identifiers of raw device related to the session end.
...
| Code Block | ||
|---|---|---|
| ||
"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,
"custom_id":string
} |
...
custom_id- a user-defined identifier of a sensor’s position that was unexpectedly released.
...
| Code Block | ||
|---|---|---|
| ||
"involved_devices":[
{
"serial_id":string,, # deprecated
"device_id": string,
"hardware_type":string,
"position":{
"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;
...
position.group_inner_id - an index number of a position in positions group;
position.labels - list of position labels
...
| Code Block | ||
|---|---|---|
| ||
"auth_ble_tag": {
"tag_id": str,
"event_time": string
} |
...
event_time- a timestamp of user authorization.
...
| Code Block | ||
|---|---|---|
| ||
"auth_mobile": {
"session_id": string,
"event_time": string
} |
...
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.
...
| Code Block | ||
|---|---|---|
| ||
{
"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_id": 1,
"labels": 1["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 | ||
|---|---|---|
| ||
{
"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.
...
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 | |||||
|---|---|---|---|---|---|
|
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.
...
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
...