Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 33 Next »

Nwave Parking Analytics provides tools for direct data visualization on dashboards or for the following processing and storage on a client-side.

The Parking Analytics API is capable of returning the following data:

  • Parking space states - filtered list of parking spaces with current occupancy information.

  • Current occupancy summary

  • Current utilization statistics.

  • Historical parking statistics - historical utilization data about parking projects, zones, levels and groups. This kind of data can be aggregated in different ways. You can find more details below.

  • History of completed parking sessions - a simple list of parking sessions, which can be filtered by session start and session end time.

You can view OpenAPI documentation here.

As an illustration of possible cases please see below the mapping of some dashboard charts to APIs described below.

Authorization

The Nwave Parking Analytics API uses header token authorization.

Authorization Tokens can be generated on the Company Info page in Nwave Console.

The generated keys must be used as the value of the HTTP header named X-Auth-Token.

You can find all information needed for authorization here.

Unobvious features

Features of processing date/time filters with options of group_by_interval

It is better to remember that analytics API can interpret arguments date_from and date_till differently in depending on the value of argument group_by_interval. If the value of group_by_interval is less than a day (e.g. 5m, 1hour, 6hours), then values of arguments date_from and date_till are interpreted as UTC time. The opposite situation is using values like day and week as values of the argument group_by_interval because in this case, the API makes calculations in the project’s timezones.

If Nwave Cloud gets a request for data about two projects located in different timezones, it tries to act in a way, which enables it to avoid ambiguous response interpretation. When a response should contain data grouped by minutes, or hours, API operates by UTC time to avoid the question “In what timezone is the data grouped”? At the same time, if the API receives a request on grouping data by days or weeks, it operates with local timezones because the midnight time is different for each timezone.

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

Let’s imagine, that there are two parking projects in timezones UTC+0 and UTC+4. Two cars get into their local parking at the same moment on Monday 20:01:00+00:00 (UTC time).

With the use of group_by_interval=1hour, we will see in the result for both projects the same: both cars have come in on Monday at 20:01:00+00.

The opposite case if the argument group_by_interval=day is passed, because the same moment of entering cars into the parking has happened on different days in local timezones:

  • the first car came into 1st project on Monday 20:01:00+00

  • the second car came into 2nd project on Tuesday 00:01:00+04:00

This way, the request won't contain data about the entry of both cars at the same time like with the use of group_by_interval=1hour. It contains data about the entry of one car on Monday and the second on Tuesday.

API Description

Parking spaces states

Parking space states API provides data on the current occupancy of the selected spaces with optional filters. The filters are:

  • 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

The API also provides pagination options:

  • limit (default value - 100) - number of returning objects

  • offset (default value - 0) - offset from the beginning of 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 returned:

{
      "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 more information about the Parking space states API here.

Current occupancy summary

This API provides wide spectrum of grouping and filtering of information about current spaces occupancy. API returns chort information about parking objects and counters of occupied and free spaces.

The API provides the following filters:

  • Project

    • Project ID

  • Zone

    • Zone ID

  • Level

    • Level D

    • Floor number

  • Group

    • Group ID

    • Custom ID

  • Position

    • Network ID

    • Label name

    • Occupancy status

Also, this API allows 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 undefined state

    • Order direction

The following example shows how to call the API for getting information about occupancy of EV spaces in zone 123 with splitting 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

Response:

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

History of completed parking sessions

This API returns a list of filtered parking session objects. The API allows to filter sessions by the following parameters:

  • Project

    • Project ID

  • Zone

    • Zone ID

  • Level

    • Level D

    • Floor number

  • Group

    • Group ID

    • Custom ID

  • Position

    • Network ID

    • Label name

    • Occupancy status

  • Session start time

  • Session end time

  • SDI tag id

The API also provides pagination options:

  • limit (default value - 100) - number of returning objects

  • offset (default value - 0) - offset from the beginning of objects list

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

The endpoint returns a slice of the parking session list from 301th to 600th objects in the following format:

{
      "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
        }
      ],
      "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 here.

Historic Utilization Statistics

The API consists of a few endpoints that provide data aggregated in different ways.

Average Utilization

Average Utilization API returns average utilization for the selected period of each position or grouped by label, group, level, zone or project.

Utilization is calculated based on the occupation time of all selected positions. For example, if you want to get utilization of a zone, that contains 10 positions for a period of 4 hours and:

  • 5 positions were occupied all the time

  • 2 positions were occupied for 3 hours

  • 3 positions were free

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

Utilization history API provides the following filters:

  • Project

    • Project ID

  • Zone

    • Zone ID

  • Level

    • Level ID

    • Floor number

  • Group

    • Group ID

    • Custom ID

  • Position

    • Network ID

    • Label name

  • Days of week - allows calculating utilization only by working days

  • Date period

  • Calculation hours window - allows calculating only between 8:00 and 18:00

The API also provides pagination options:

  • limit (default value - 100) - number of returning objects

  • offset (default value - 0) - offset from the beginning of objects list

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'

The response structure depends on the grouping option you chose:

{
    "grouped_by": "position",
    "data": [
      {
        "utilization": 0,
        "position": {
          "id": 0,
          "network_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "custom_id": "string"
        }
      }
    ]
  }
{
    "grouped_by": "label",
    "data": [
      {
        "utilization": 0,
        "label": {
          "name": "string"
        }
      }
    ]
  }
{
    "grouped_by": "group",
    "data": [
      {
        "utilization": 0,
        "group": {
          "id": 0,
          "name": "string"
        }
      }
    ]
  }
{
    "grouped_by": "level",
    "data": [
      {
        "utilization": 0,
        "level": {
          "id": 0,
          "name": "string",
          "floor_number": 0
        }
      }
    ]
  }
{
    "grouped_by": "zone",
    "data": [
      {
        "utilization": 0,
        "zone": {
          "id": 0,
          "name": "string"
        }
      }
    ]
  }
{
    "grouped_by": "project",
    "data": [
      {
        "utilization": 0,
        "project": {
          "id": 0,
          "name": "string"
        }
      }
    ]
  }

You can find more information about the Parking spaces states API here.

Utilization history

Utilization history API provides a history 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

  • hour

  • 2 hours

  • 3 hours

  • 4 hours

  • 6 hours

  • 12 hours

  • day

  • week

API provides the following filters:

  • Project

    • Project ID

  • Zone

    • Zone ID

  • Level

    • Level ID

    • Floor number

  • Group

    • Group ID

    • Custom ID

  • Position

    • Network ID

    • Label name

  • Days of week - allows calculating utilization only for selected days of week, e.g. working days Mon-Fri

  • Date period

  • Calculation hours window - allows calculating only between 8:00 and 18:00

The API also provides pagination options:

  • limit (default value - 100) - number of returning objects

  • offset (default value - 0) - offset from the beginning of objects list

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.

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:

{
    "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 of the calculation period

  • sessions_count - number of parking sessions for the period

  • occupied_spaces_count - number of spaces that were involved in at least one parking session

  • utilization - see the utilization explanation in the previous chapter

You can find more information about the Parking spaces states API here.

Utilization Heatmap

Utilization heatmap API provides data that can be displayed on the heatmap grid, where the intensity of colour for each square on that grid is proportional to the utilization value (0-100).

The utilization history can be grouped by project, zone, level, group, position, label and can be aggregated in the following time periods:

  • day

  • hour

API provides the following 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 week - allows calculating utilization only by working days

  • Calculation hours window - allows calculating only between 8:00 and 18:00

The API also provides pagination options:

  • limit (default value - 100) - number of returning objects

  • offset (default value - 0) - offset from the beginning of the objects list

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

{
    "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 the Utilization Heatmap API here.

[Under Construction] Parking session duration

Session duration history API provides the history of parking session duration that can be grouped by project, zone, level, group, position, label.

API provides the following 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 week - allows calculating utilization only by working days

  • Calculation hours window - allows calculating only between 8:00 and 18:00

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'

Response

{
    "grouped_by": "zone",
    "data": [
      {
        "zone": {
          "id": 0,
          "name": "Zone name",
        },
        "datetime": "2021-08-13",
        "duration": 0 # minutes
      }
    ]
}

You can find more information about the Parking session duration API here.

  • No labels