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

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

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

You can find more information about the Parking space 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

    • LevelI D

    • Floor number

  • Group

    • Group ID

    • Custom ID

  • Position

    • Network ID

    • Label name

    • Occupancy status

  • Session start time

  • Session end time

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

The endpoint returns a list of parking session 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
          },
          "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

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'

The response structure depends on the grouping option you chose:

{
    "grouped_by": "position",
    "total_utilization": 0,
    "data": [
      {
        "utilization": 0,
        "position": {
          "id": 0,
          "network_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "custom_id": "string"
        }
      }
    ]
  }
{
    "grouped_by": "label",
    "total_utilization": 0,
    "data": [
      {
        "utilization": 0,
        "label": {
          "name": "string"
        }
      }
    ]
  }
{
    "grouped_by": "group",
    "total_utilization": 0,
    "data": [
      {
        "utilization": 0,
        "group": {
          "id": 0,
          "name": "string"
        }
      }
    ]
  }
{
    "grouped_by": "level",
    "total_utilization": 0,
    "data": [
      {
        "utilization": 0,
        "level": {
          "id": 0,
          "name": "string",
          "floor_number": 0
        }
      }
    ]
  }
{
    "grouped_by": "zone",
    "total_utilization": 0,
    "data": [
      {
        "utilization": 0,
        "zone": {
          "id": 0,
          "name": "string"
        }
      }
    ]
  }
{
    "grouped_by": "project",
    "total_utilization": 0,
    "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:

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

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.

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
      }
    ]
}

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

Working Hours

Working hours are the hours of operation for a given zone. Different zones can have different hours of operation for their parking spaces. Working hours are necessary to define the time boundaries for calculating analytics. Working hours API provides a way of retrieving and updating working hours.

Updating working hours

In order to update the working hours of the zone, you need to provide a list of days as well as the start and finish of the working hours period.

Example of request that updates working hours for zone with id 3:

curl -v \
  -H 'x-Auth-Token: 1234567890ABCDEF' \
  -X POST \
  -d '{"day_of_week": ["mon"], "start_hours": "08:00:00", "finish_hours": "20:00:00"}' \
  'https://api.nwave.io/analytics/v1/working_hours/3'

Response

{
  "day_of_week": ["mon"], 
  "start_hours": "08:00:00", 
  "finish_hours": "20:00:00"
}

You can find more information about the Working Hours API here.

Getting working hours

There are two ways you can retrieve working hours.

  1. For an individual zone

  2. For a list a filtered list of zones

Getting working hours for a zone

Example of retrieving working hours for zone with id 3:

curl -v \
  -H 'x-Auth-Token: 1234567890ABCDEF' \
  'https://api.nwave.io/analytics/v1/working_hours/3'

Response

{
  "day_of_week": ["mon"], 
  "start_hours": "08:00:00", 
  "finish_hours": "20:00:00"
}

Getting working hours with filters

API provides the following optional filters:

  • Project

    • Project ID

  • Zone

    • Zone ID

Example request that filter by project with id 1 and zone with 2:

curl -v \
  -H 'x-Auth-Token: 1234567890ABCDEF' \
  'https://api.nwave.io/analytics/v1/working_hours?proect_id=1&zone_id=2'

Response

{
  "zone_id": 314,
  "day_of_week": ["mon"], 
  "start_hours": "08:00:00", 
  "finish_hours": "20:00:00"
}

You can find more information about the Working Hours API here.

  • No labels