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

1. To generate Authorization Tokens

...

1. , navigate to the 'Company Info' page

...

1. within the Nwave Console.

2. The

...

1. keys generated on this page should be utilized as the value

...

1. for the HTTP header named X-Auth-Token

...

1. when making API requests.

For a comprehensive guide on authorization, including detailed information and steps, please refer to the provided documentation.

Unobvious features

Features of processing date/time filters with options of group_by_interval

...

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

...

1. arguments varies depending on the

...

1. chosen group_by_interval. If

...

1. group_by_interval is

...

1. set to a value smaller than a day (e.g.

...

1. ,

...

1. 5 minutes, 1 hour, 6 hours), the date_from and date_till values are interpreted

...

1. in UTC time.

...

1. On the other hand, when using values like 'day' and 'week' as

...

1. group_by_interval

...

1. , the API

...

1. performs calculations in the

...

1. project's respective timezones.

...

1. Handling Multiple Timezones: Nwave Cloud

...

1. handles requests for data

...

1. from projects located in different timezones

...

1. carefully to avoid ambiguous response interpretation.

...

1. Specifically:

   • When data needs to be grouped by minutes

...

1. • or hours, the API operates

...

1. • in UTC time to

...

This approach leads to unobvious behavior. Let's look at an example:

...

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

  came into

  • entered the 1st project on Monday at 20:01:00+00:00.

  the

  • The second car

  came into

  • entered the 2nd project on Tuesday at 00:01:00

  +04: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

  number

  Number

• Group

• Group ID

• Custom ID

• Position

• Network ID

• Label ID

• Label

  name

  Name

• Occupancy

  status

  Status

The API also provides Additionally, the API offers pagination options:

• limit (default value - 100) - : Specifies the number of returning 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'

As a result of query execution the following data structures are returnedUpon 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"
      },
      "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

  D

  ID

• Floor

  number

  Number

• Group

• Group ID

• Custom ID

• Position

• Network ID

• Label

  name

  Name

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

  Parking Object

• Number of

  • Parking

    spaces

    Spaces (

    total

    Total)

  • Occupied

    spaces

    Spaces

  • Available

    spaces

  • Spaces in undefined state

  • Order direction

...

• • Spaces

  • Spaces in an Undefined State

Order 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:

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.

{
   "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

  D

  ID

• Floor

  number

  Number

• Group

• Group ID

• Custom ID

• Position

• Network ID

• Label

  name

  Name

• Occupancy

  status

  Status

• Session start timeStart Time

• Session end timeEnd Time

• SDI tag idTag ID

Pagination Options

The API also provides pagination optionssupports pagination to help manage large datasets:

• limit (default value - 100) - : Specifies the number of returning 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:

curl -v -H 'x-Auth-Token: 1234567890ABCDEF' 'https://api.nwave.io/analytics/v1/history/sessions?limit=300&offset=300'

API Response

The endpoint returns API response includes a slice of the parking session list from 301th to 600th objects in the following formatparking session data, with details such as the parking session UUID, involved positions, session start and end times, and authorization information.at:

{
      "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": [
            "string"
          ]
        }
      ],
      "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

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

  number

  Number

• Group

• Group ID

• Custom ID

• Position

• Network ID

• Label

  name

  Name

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

Pagination Options

To manage large datasets, the API supports pagination:

• limit (default value - 100) - : Determines the number of returning objects to return per request.

• offset (default value - 0) - : Specifies the offset from the beginning of objects listthe objects list.

Example API Request

Below is an example of an API request to retrieve utilization data:

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.

{
    "grouped_by": "position",
    "data": [
      {
        "utilization": 0,
        "position": {
          "id": 0,
          "network_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "custom_id": "string"
        }
      }
    ]
  }

...

{
    "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

  number

  Number

• Group

• Group ID

• Custom ID

• Position

• Network ID

• Label

  name

  Name

• 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 and 18: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 returning 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:

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'

...

=hour&date_from=2021-07-12&date_till=2021-07-13'

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:

{
    "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:

• dayDay

• Hour

• hour

...

Filters

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

• Project

• Project ID

• Zone

• Zone ID

• Level

• Level ID

• Floor

  number

  Number

• Group

• Group ID

• Custom ID

• Position

• Network ID

• Label

  name

  Name

• Date periodPeriod

• Days of week - allows calculating utilization only by working daysCalculation hours window - allows calculating only 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 186:00

...

• PM).

Pagination Options

For effective data management, the API supports pagination:

• limit (default value - 100) - : Specifies the number of returning 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:

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'

...

'

API Response

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

{
    "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

  number

  Number

• Group

• Group ID

• Custom ID

• Position

• Network ID

• Label

  name

  Name

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

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.

{
    "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.