Per-Space Parking Analytics API

Owned by
Nikolay Abrosimov
Last updated: Oct 09, 2023

Nwave Parking Analytics offers a suite of tools designed for data visualization directly on dashboards or for client-side data processing and storage.

The Parking Analytics API provides access to a range of data, including:

  • Parking Space States: Obtain a filtered list of parking spaces with real-time occupancy information.

  • Current 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 data is versatile and can be aggregated in various ways to suit your specific requirements. Further details on aggregation options are available below.

  • History of Completed Parking Sessions: Access a simple list of parking sessions, which can be filtered based on session start and end times. This feature is valuable for tracking and analyzing parking history.

You can view OpenAPI documentation here.

As an illustrative example of potential use cases, please find below a mapping of specific dashboard charts to the corresponding APIs described earlier.

Authorization with Header Tokens

The Nwave Parking Analytics API employs header token authorization for secure access.

  1. To generate Authorization Tokens, navigate to the 'Company Info' page within the Nwave Console.

  2. 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 option. Here are some key considerations:

  1. Date/Time Interpretation: The API's behavior related to the date_from and date_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 and date_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.

  2. 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 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. Both have cars entering at the same moment on Monday at 20:01:00+00:00 (UTC time).

  • 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 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=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 API provides real-time data on the current occupancy of selected parking spaces, along with optional filters. These filters include:

  • Project

  • Project ID

  • Zone

  • Zone ID

  • Level

  • Level ID

  • Floor Number

  • Group

  • Group ID

  • Custom ID

  • Position

  • Network ID

  • Label ID

  • Label Name

  • 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.

curl -v -H 'x-Auth-Token: 1234567890ABCDEF' 'https://api.nwave.io/analytics/v1/realtime/state'

Upon executing the query, the API returns data structured as follows:

{ "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" }, "labels": [ "string" ], "zone_name": "string", "group_name": "string", "project_name": "string", "level_name": "string" }

For more detailed information about the Parking Space 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 information about current parking space occupancy. This API provides concise information about parking objects, including counts of occupied and free spaces.

Filters

The API supports various filters, including:

  • Project

  • Project ID

  • Zone

  • Zone ID

  • Level

  • Level ID

  • Floor Number

  • Group

  • Group ID

  • Custom ID

  • Position

  • Network ID

  • Label Name

  • Occupancy 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 Object

  • Number of

    • Parking Spaces (Total)

    • Occupied Spaces

    • Available Spaces

    • Spaces in an Undefined State

Order Direction:

  • Ascending

  • Descending

Example API Request

Here is an example of how to call the API to retrieve information about the occupancy of Electric Vehicle (EV) spaces in Zone 123, grouped by levels:

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.

For 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, 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 ID

  • Floor Number

  • Group

  • Group ID

  • Custom ID

  • Position

  • Network ID

  • Label Name

  • Occupancy Status

  • Session Start Time

  • Session End Time

  • SDI 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:

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:

For more comprehensive details and usage examples, please refer to the API documentation.

Historic Utilization Statistics API

The Historic Utilization Statistics API provides access to data aggregated in various ways, including Average Utilization. This API allows you to retrieve average utilization data for 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

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 over a 4-hour period, where:

  • 5 positions were occupied continuously

  • 2 positions were occupied for 3 hours

  • 3 positions remained unoccupied

The utilization is calculated as follows: ((5 * 4) + (2 * 3)) / (10 * 4) = 65%

Filters

The Utilization History API offers a range of filters to customize your queries:

  • Project

  • Project ID

  • Zone

  • Zone ID

  • Level

  • Level ID

  • Floor Number

  • Group

  • Group ID

  • Custom ID

  • Position

  • Network ID

  • Label Name

  • Days of 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 6:00 PM).

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:

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 utilization data corresponding to the specified parameters.

For more detailed information and usage examples, please refer to the API documentation.

Utilization History API

The Utilization History API provides a historical record of utilization 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 Number

  • Group

  • Group ID

  • Custom ID

  • Position

  • Network ID

  • Label Name

  • Days of the Week: Allows you to calculate utilization for specific days of the week (e.g., working days 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 6:00 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:

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:

  • datetime: Timestamp of the calculation period.

  • sessions_count: Number of parking sessions for the period.

  • occupied_spaces_count: Number of spaces involved in at least one parking session.

  • utilization: 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 API provides data that can be used to create heatmaps, where the color intensity of each square 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.

You can also aggregate data over different time periods:

  • Day

  • Hour

Filters

To tailor your heatmap data, the API offers several filters:

  • Project

  • Project ID

  • Zone

  • Zone ID

  • Level

  • Level ID

  • Floor Number

  • Group

  • Group ID

  • Custom ID

  • Position

  • Network ID

  • Label 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:

API Response

The API response includes data suitable for generating heatmaps. It provides information about zones, utilization percentages, week days, and specific times:

For comprehensive details and additional usage examples, please refer to the Utilization Heatmap API documentation.

Parking Session Duration API [Under Construction]

The Session Duration History API, currently under construction, will provide a historical record of parking session durations. This data can be grouped by various criteria, including project, zone, level, group, position, and label.

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 Number

  • Group

  • Group ID

  • Custom ID

  • Position

  • Network ID

  • Label Name

  • Date Period

  • Days of the 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:

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.

Please stay tuned for updates on the availability of this API. More information about the Parking Session Duration API will be provided once it becomes accessible.

Â