Table of Contents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
Nwave Parking Analytics provides offers a suite of tools designed for direct data visualization directly on dashboards or for the following client-side data processing and storage on a client-side.
The Parking Analytics API is capable of returning the following dataprovides access to a range of data, including:
Parking space states - Space States: Obtain a filtered list of parking spaces with current real-time occupancy information.
Current occupancy summary
Current utilization statistics.
Historical parking statistics - historical utilization data about Occupancy Summary: Access a concise overview of current utilization statistics for parking spaces.
Current Utilization Statistics: Explore detailed statistics to understand the current usage of parking spaces.
Historical Parking Statistics: Access historical utilization data related to parking projects, zones, levels, and groups. This kind of data is versatile and can be aggregated in different various ways . You can find more details to suit your specific requirements. Further details on aggregation options are available below.
History of completed parking sessions - Completed Parking Sessions: Access a simple list of parking sessions, which can be filtered by based on session start and session end time.
...
times. This feature is valuable for tracking and analyzing parking history.
You can view OpenAPI documentation here.
As an illustration illustrative example of possible potential use cases, please see find below the a mapping of some specific dashboard charts to the corresponding APIs described belowearlier.
...
Authorization with Header Tokens
The Nwave Parking Analytics API uses employs header token authorization for secure access.
To generate Authorization Tokens
...
, navigate to the 'Company Info' page
...
within the Nwave Console.
The
...
keys generated on this page should be utilized as the value
...
for the HTTP header named X-Auth-Token
...
when making API requests.
For a comprehensive guide on authorization, including detailed information and steps, please refer to the provided documentation.
Unobvious features
...
Handling Date/Time Filters and Grouping Intervals
When working with the Nwave Parking Analytics API, it's important to understand how date/time filters
...
are processed, especially when using the group_by_interval
...
It is better to remember that analytics API can interpret arguments option. Here are some key considerations:
Date/Time Interpretation: The API's behavior related to the
date_from
anddate_till
...
arguments varies depending on the
...
chosen
group_by_interval
. If
...
group_by_interval
is
...
set to a value smaller than a day (e.g.
...
, 5 minutes, 1 hour, 6 hours), the
date_from
anddate_till
values are interpreted
...
in UTC time.
...
On the other hand, when using values like 'day' and 'week' as
...
group_by_interval
...
, the API
...
performs calculations in the
...
project's respective timezones.
...
Handling Multiple Timezones: Nwave Cloud
...
handles requests for data
...
from projects located in different timezones
...
carefully to avoid ambiguous response interpretation.
...
Specifically:
When data needs to be grouped by minutes
...
or hours, the API operates
...
in UTC time to
...
This approach leads to unobvious behavior. Let's look at an example:
...
eliminate ambiguity about the timezone of the grouped data.
However, when data grouping is based on days or weeks, the API respects local timezones, as the concept of "midnight" varies across timezones.
Example Illustration:
Imagine two parking projects in different timezones, UTC+0 and UTC+4. Two cars get into their local parking Both have cars entering at the same moment on Monday at 20:01:00+00:00 (UTC time).With the
If you use
...
group_by_interval=1hour
,
...
the API will
...
show the same result for both projects
...
, indicating that both cars
...
entered on Monday at 20:01:00+00:00.
...
Conversely, if you use
group_by_interval=day
...
,
...
the API accounts for the different local timezones:the
The first car
entered the 1st project on Monday at 20:01:00+00:00.
The second car
entered the 2nd project on Tuesday at 00:01:00+04:00
...
.
With group_by_interval=
1hour. It day
, the request contains data about the entry of one car on Monday and the second car on Tuesday, reflecting the local time differences.
API Description
Parking
...
Space States API
The Parking space states Space States API provides real-time data on the current occupancy of the selected parking spaces, along with optional filters. The These filters areinclude:
Project
Project ID
Zone
Zone ID
Level
Level ID
Floor
numberNumber
Group
Group ID
Custom ID
Position
Network ID
Label ID
Label
nameOccupancy statusName
Occupancy Status
Additionally, the API offers pagination options:
limit (default value - 100): Specifies the number of objects to return.
offset (default value - 0): Determines the offset from the beginning of the objects list.
Code Block | ||
---|---|---|
| ||
curl -v -H 'x-Auth-Token: 1234567890ABCDEF' 'https://api.nwave.io/analytics/v1/realtime/state' |
As a result of query execution the following data structures are returnedUpon executing the query, the API returns data structured as follows:
Code Block | ||
---|---|---|
| ||
{
"network_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"custom_id": "string",
"group_id": 0,
"zone_id": 0,
"owner_id": 0,
"project_id": 0,
"occupied": true,
"status_time": "2021-07-12T18:18:03.497Z",
"lat": 0,
"lon": 0,
"level_id": 0,
"floor_number": 0,
"authorization": {
"id": "string",
"type": "string",
"registration_time": "2021-07-12T18:18:03.497Z"
},
"label_ids": [
0
],
"labels": [
"string"
],
"zone_name": "string",
"group_name": "string",
"project_name": "string",
"level_name": "string"
} |
You can find For more detailed information about the Parking space states API hereSpace States API, please refer to the API documentation.
Current
...
Occupancy Summary API
The Current Occupancy Summary API offers a comprehensive set of options for grouping and filtering of information about current spaces parking space occupancy. This API returns chort provides concise information about parking objects and counters , including counts of occupied and free spaces.
Filters
The API provides the following filterssupports various filters, including:
Project
Project ID
Zone
Zone ID
Level
Level
DID
Floor
numberNumber
Group
Group ID
Custom ID
Position
Network ID
Label
nameName
Occupancy
status
...
Status
Grouping and Ordering Options
Additionally, this API allows you to configure grouping and ordering options:
Grouping by
...
Parking Object Types:
Project
Zone
Level
Group
Label
Ordering
...
By:
Name of
parking objectParking Object
Number of
Parking
spacesSpaces (
totalTotal)
Occupied
spacesSpaces
Available
spacesSpaces
Spaces in
undefined statean Undefined State
Order
...
The following example shows how Direction:
Ascending
Descending
Example API Request
Here is an example of how to call the API for getting to retrieve information about the occupancy of Electric Vehicle (EV) spaces in zone Zone 123 with splitting , grouped by levels:
Code Block | ||
---|---|---|
| ||
curl -H 'x-Auth-Token: 1234567890ABCDEF' 'https://api.nwave.io/analytics/v1/realtime/occupancy_summary?zone_id=123&labels=EV&group_by=level |
...
API Response
The API response provides a summary of occupancy data, including counts of total, occupied, available, and undefined spaces, grouped by levels.
Code Block | ||
---|---|---|
| ||
{ "message":null, "data":{ "grouped_by":"level", "total":3, "data":[ { "level":{ "id":111, "name":"A", "floor_number":1 }, "summary":{ "total":16, "occupied":6, "available":10, "undefined":0 } }, { "level":{ "id":112, "name":"B", "floor_number":2 }, "summary":{ "total":53, "occupied":43, "available":10, "undefined":0 } }, { "level":{ "id":113, "name":"C", "floor_number":3 }, "summary":{ "total":45, "occupied":44, "available":1, "undefined":0 } } ] }, "reason":"ok" } |
You can find more information about the Parking spaces states API hereFor more in-depth details and usage examples, please refer to the API documentation.
History of
...
Completed Parking Sessions API
The History of Completed Parking Sessions API provides a list of filtered parking session objects. The API allows to filter sessions by the following parameters, allowing you to retrieve detailed information about past parking sessions. You can filter sessions using various parameters, including:
Project
Project ID
Zone
Zone ID
Level
Level
DID
Floor
numberNumber
Group
Group ID
Custom ID
Position
Network ID
Label
nameName
Occupancy
statusStatus
Session start timeStart Time
Session end timeEnd Time
SDI tag id
...
Tag ID
Pagination Options
The API also supports pagination to help manage large datasets:
limit (default value - 100): Specifies the number of objects to return per request.
offset (default value - 0): Determines the offset from the beginning of the objects list.
Example API Request
Here's an example of how to call the API to retrieve parking session data with a limit of 300 and an offset of 300:
Code Block | ||
---|---|---|
| ||
curl -v -H 'x-Auth-Token: 1234567890ABCDEF' 'https://api.nwave.io/analytics/v1/history/sessions' |
...
?limit=300&offset=300' |
API Response
The API response includes a slice of parking session data, with details such as the parking session UUID, involved positions, session start and end times, and authorization information.at:
Code Block | ||
---|---|---|
| ||
{ "parking_session_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "involved_positions": [ { "network_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "custom_id": "string", "latitude": 0, "longitude": 0, "group": { "id": 0, "type": "string", "name": "string", "custom_id": "string", "zone_id": 0, "level_id": 0, "floor_number": 0, "level_name": "string" }, "group_inner_id": 0, }"labels": [ ], "session_startstring": "2021-07-12T18:34:18.354Z", " ] } ], "session_start": "2021-07-12T18:34:18.354Z", "session_end": "2021-07-12T18:34:18.354Z", "authorization": { "id": "string", "type": "sdi_tag", "registration_time": "2021-07-12T18:34:18.354Z" } } |
You can find more information about the Parking spaces states API hereFor more comprehensive details and usage examples, please refer to the API documentation.
Historic Utilization Statistics API
The API consists of a few endpoints that provide Historic Utilization Statistics API provides access to data aggregated in different various ways., including Average Utilization
...
Average Utilization API returns . This API allows you to retrieve average utilization data for the selected period of each position or grouped by label, group, level, zone or project.
...
selected positions, labels, groups, levels, zones, or projects over specific time periods. Utilization is calculated based on the occupation time of
...
the selected positions.
...
Average Utilization
Info |
---|
The Average Utilization API returns the average utilization for the chosen period. For instance, if you want to determine the utilization of a zone , that contains 10 positions for over a period of 4 hours and4-hour period, where:
The utilization is calculated like thisas follows: ((5 * 4) + (2 * 3)) / (10 * 4) = 65% |
Filters
The Utilization history API provides the following filtersHistory API offers a range of filters to customize your queries:
Project
Project ID
Zone
Zone ID
Level
Level ID
Floor
numberNumber
Group
Group ID
Custom ID
Position
Network ID
Label
nameName
Days of week - allows calculating utilization only by working days
Date period
Calculation hours window - allows calculating only the Week: Allows you to calculate utilization exclusively on working days.
Date Period: Specify the desired time range.
Calculation Hours Window: Define the time window within which calculations are performed (e.g., between 8:00 AM and 186:00 PM).
...
language | bash |
---|
...
Pagination Options
To manage large datasets, the API supports pagination:
limit (default value - 100): Determines the number of objects to return per request.
offset (default value - 0): Specifies the offset from the beginning of the objects list.
Example API Request
Below is an example of an API request to retrieve utilization data:
Code Block | ||
---|---|---|
| ||
curl -v -H 'x-Auth-Token: 1234567890ABCDEF' 'https://api.nwave.io/analytics/v1/history/aggregate/avg?group_by=zone&date_from=2021-07-12&date_till=2021-07-13&control_hours_from=08:00:00&control_hours_till=18:00:00&day_of_week=mon&day_of_week=tue' |
API Response
The structure of the API response structure depends on the grouping option you chose:chosen grouping option, such as position, label, group, level, zone, or project. It includes utilization data corresponding to the specified parameters.
Code Block | ||
---|---|---|
| ||
{ "grouped_by": "position", "data": [ { "utilization": 0, "position": { "id": 0, "network_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "custom_id": "string" } } ] } |
...
Code Block | ||
---|---|---|
| ||
{ "grouped_by": "project", "data": [ { "utilization": 0, "project": { "id": 0, "name": "string" } } ] } |
You can find For more information about the Parking spaces states API heredetailed information and usage examples, please refer to the API documentation.
Utilization
...
History API
The Utilization history History API provides a history historical record of utilization of each position or many positions grouped by label, group, level, zone or project. The utilization history can be aggregated in the following time periods:
...
5 mins
...
10mins
...
15mins
...
20mins
...
30mins
data for individual parking positions or groups of positions based on labels, groups, levels, zones, or projects. Utilization data can be aggregated over various time periods, making it a valuable tool for understanding parking space usage.
Aggregation Time Periods
The API allows you to aggregate utilization data over the following time intervals:
5 minutes
10 minutes
15 minutes
20 minutes
30 minutes
1 hour
2 hours
3 hours
4 hours
6 hours
12 hours
1 day
1 week
...
Filters
To tailor your utilization history queries, the API offers a wide range of filters, including:
Project
Project ID
Zone
Zone ID
Level
Level ID
Floor
numberNumber
Group
Group ID
Custom ID
Position
Network ID
Label
nameName
Days of week - allows calculating utilization only for selected days of week, the Week: Allows you to calculate utilization for specific days of the week (e.g., working days Mon-Fri
Date period
Calculation hours window - allows calculating only from Monday to Friday).
Date Period: Specify the desired time range.
Calculation Hours Window: Define the time window for utilization calculations (e.g., between 8:00 AM and 186:00
The response object can be different and depends on the grouping you chose. The structure of project/zone/level/group/position/label object was described in the previous chapter.
...
PM).
Pagination Options
To manage large datasets efficiently, the API supports pagination with the following options:
limit (default value - 100): Specifies the number of objects to return per request.
offset (default value - 0): Determines the offset from the beginning of the objects list.
Example API Request
Here is an example of an API request to retrieve utilization data, grouped by zones and aggregated on an hourly basis:
Code Block |
---|
curl -v -H 'x-Auth-Token: 1234567890ABCDEF' 'https://api.nwave.io/analytics/v1/history/chart/avg?group_by=zone&group_by_interval=hour&date_from=2021-07-12&date_till=2021-07-13' |
Endpoint return data in the following format:
...
language | json |
---|
...
API Response
The structure of the API response depends on the chosen grouping option, such as position, label, group, level, zone, or project. It includes meaningful fields like datetime
, sessions_count
, occupied_spaces_count
, and utilization
. The object structure corresponds to the chosen grouping type.
For example:
Code Block | ||
---|---|---|
| ||
{
"grouped_by": "position",
"grouped_by_interval": "hour",
"data": [
{
"datetime": "string",
"sessions_count": 0,
"occupied_spaces_count": 0,
"utilization": 0,
"position": { // this object structure is depent on grouping type
"id": 0,
"network_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"custom_id": "string"
}
}
]
} |
Meaningful fields description:
datetime - timestamp datetime: Timestamp of the calculation period.
sessions_count - number : Number of parking sessions for the period.
occupied_spaces_count - number : Number of spaces that were involved in at least one parking session.
utilization - see the utilization explanation in the : Utilization value (explained in a previous chapter
...
).
For comprehensive details and additional usage examples, please refer to the API documentation.
Utilization Heatmap API
The Utilization heatmap Heatmap API provides data that can be displayed on the heatmap gridused to create heatmaps, where the color intensity of colour for each square on that grid is proportional corresponds to the utilization value (ranging from 0 -to 100).
Aggregation Options
The utilization history can be grouped by project, zone, level, group, position , and label and can be aggregated in the following .
You can also aggregate data over different time periods:
Day
dayHour
hour
...
Filters
To tailor your heatmap data, the API offers several filters:
Project
Project ID
Zone
Zone ID
Level
Level ID
Floor
numberNumber
Group
Group ID
Custom ID
Position
Network ID
Label name
Date period
Days of week - allows calculating utilization only by working days
Calculation hours window - allows calculating only between 8:00 and 18:00Label Name
Date Period
Days of the Week: Allows you to calculate utilization exclusively on working days (e.g., Monday to Friday).
Calculation Hours Window: Specify the hours during which calculations are performed (e.g., between 8:00 AM and 6:00 PM).
Pagination Options
For effective data management, the API supports pagination:
limit (default value - 100): Specifies the number of objects to return per request.
offset (default value - 0): Determines the offset from the beginning of the objects list.
Example API Request
Here's an example API request to retrieve utilization data, grouped by zones and aggregated on an hourly basis:
Code Block | ||
---|---|---|
| ||
curl -v -H 'x-Auth-Token: 1234567890ABCDEF' 'https://api.nwave.io/analytics/v1/history/heatmap?group_by=zone&group_by_interval=hour&date_from=2021-07-12&date_till=2021-07-13' |
Response
API Response
The API response includes data suitable for generating heatmaps. It provides information about zones, utilization percentages, week days, and specific times:
Code Block | ||
---|---|---|
| ||
{ "grouped_by": "zone", "grouped_by_interval": "hour", "data": [ { "zone": { "id": 1, "name": "Zone name" }, "utilization": 50, "week_day": "mon", "time": "11:00:00" } ] } |
You can find more information about For comprehensive details and additional usage examples, please refer to the Utilization Heatmap API heredocumentation.
Parking Session Duration API [Under Construction]
...
The Session duration history API provides the history Duration History API, currently under construction, will provide a historical record of parking session duration that durations. This data can be grouped by various criteria, including project, zone, level, group, position, and label.API provides the following filters
Filters
Once completed, this API will offer a range of filters to refine your queries:
Project
Project ID
Zone
Zone ID
Level
Level ID
Floor
numberNumber
Group
Group ID
Custom ID
Position
Network ID
Label
nameName
Date periodPeriod
Days of week - allows calculating utilization only by working daysCalculation hours window - allows calculating only between 8:00 and 18:00the Week: Will allow you to calculate session durations specifically for working days.
Calculation Hours Window: Will enable calculations within specified hours (e.g., between 8:00 AM and 6:00 PM).
Example API Request
Once completed, you will be able to make API requests to retrieve session duration data. An example request might look like this:
Code Block | ||
---|---|---|
| ||
curl -v -H 'x-Auth-Token: 1234567890ABCDEF' 'https://api.nwave.io/analytics/v1/history/aggregate/session_duration/avg?group_by=zone&date_from=2021-07-12&date_till=2021-07-13' |
API Response
The API response, when fully implemented, will provide data about session durations suitable for analysis. It may include information about zones, timestamps, and session durations in minutes.
Code Block | ||
---|---|---|
| ||
{ "grouped_by": "zone", "data": [ { "zone": { "id": 0, "name": "Zone name", }, "datetime": "2021-08-13", "duration": 0 # minutes } ] } |
You can find more Please stay tuned for updates on the availability of this API. More information about the Parking session duration API hereSession Duration API will be provided once it becomes accessible.