Car Counters Analytics API

Owned by
Nikolay Abrosimov
Last updated: Oct 10, 2023
7 min read

Nwave Car Counter Analytics API offers a comprehensive set of tools for parking analysis. Please refer to the screenshot below, which displays analytics charts along with the corresponding API endpoint names. You can select the specific API that aligns with your analysis objectives.

You can view OpenAPI documentation here.

 

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.

API Description

Realtime Occupancy Summary API

URL: https://api.nwave.io/analytics/v1/car_counters/realtime/occupancy_summary

Method: GET

Query Arguments:

  • group_by: Group results by project, zone, level, or group.

    • Allowed values: project, zone, group, level

  • project_id: One or multiple project IDs.

  • zone_id: One or multiple zone IDs.

  • level_id: One or multiple level IDs.

  • floor_number: One or multiple floor numbers.

  • group_id: One or multiple group IDs.

  • group_custom_id: One or multiple group custom IDs.

  • order_by: Specify the ordering key.

    • Allowed values: name, occupied

    • Default: name

  • order_direction: Specify the ordering direction.

    • Allowed values: asc, desc

    • Default: asc

Pagination:

  • limit: Maximum number of objects in the response.

    • Default: 100

  • offset: Number of skipped objects from the beginning of the result.

    • Default: 0

Example:

Retrieve the current occupancy of all groups in zone with ID 123:

curl --request GET 'https://api.nwave.io/analytics/v1/car_counters/realtime/occupancy_summary?group_by=group&zone_id=123' --header 'x-Auth-Token: XXXXXXXXXXXX'

Response:

{ "message": "string", "data": { "grouped_by": "project", "total": 0, "data": [ { "group": { "capacity": 0, "id": 0, "name": "string" }, "occupied": 0 } ] }, "reason": "ok" }

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

Occupancy History API

URL: https://api.nwave.io/analytics/v1/car_counters/history/chart/raw

Method: GET

Query Arguments:

  • group_by: Group results by project, zone, level, or group.

    • Allowed values: project, zone, group, level

  • date_from: UTC timestamp. Example: 2023-01-10

  • date_till: UTC timestamp. Example: 2023-01-10

  • project_id: One or many project IDs.

  • zone_id: One or many zone IDs.

  • level_id: One or many level IDs. Pass 0 to select groups out of level (directly in the zone).

  • order_by: Specify the ordering key.

    • Allowed values: name, occupied

    • Default: name

  • order_direction: Specify the ordering direction.

    • Allowed values: asc, desc

    • Default: asc

Pagination:

  • limit: Maximum number of objects in the response.

    • Default: 100

  • offset: Number of skipped objects from the beginning of the result.

    • Default: 0

Example:

Request zone occupancy with ID 123 between December 10, 2022, and January 10, 2023:

curl --location --request GET 'https://api.nwave.io/analytics/v1/car_counters/history/chart/raw?zone_id=123&date_from=2022-12-10&date_till=2023-01-10' --header 'x-Auth-Token: XXXXXXXXXXXX'

Response:

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

Aggregated average occupancy API

URL: https://api.nwave.io/analytics/v1/car_counters/history/aggregate/avg

Method: GET

Query Arguments:

  • group_by: Group results by project, zone, level, or group.

    • Allowed values: project, zone, group, level

  • date_from: UTC timestamp. Example: 2023-01-10

  • date_till: UTC timestamp. Example: 2023-01-10

  • day_of_week: mon, tue, wed, thu, fri, sat, sun

  • control_hours_from: Example: 08:00:00, minutes and seconds are truncated

  • control_hours_till:Example: 21:00:00, minutes and seconds are truncated

  • project_id: One or many project IDs.

  • zone_id: One or many zone IDs.

  • group_id: One or many group IDs.

  • group_custom_id: One or many group custom IDs.

  • floor_number: one or many floor numbers

  • level_id: One or many level IDs. Pass 0 to select groups out of level (directly in the zone).

  • order_by: Specify the ordering key.

    • Allowed values: name, occupied

    • Default: name

  • order_direction: Specify the ordering direction.

    • Allowed values: asc, desc

    • Default: asc

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.

Example:

Request average occupancy of a zone with ID 123 between December 10, 2022, and January 10, 2023:

Response:

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

Average occupancy history API

URL: https://api.nwave.io/analytics/v1/car_counters/history/chart/avg

Method: GET

Query Arguments:

  • group_by: Group results by project, zone, level, or group.

    • Allowed values: project, zone, group, level

  • group_by_interval:

    • Available values : 5m, 10m, 15m, 20m, 30m, hour, 2h, 3h, 4h, 6h, 12h, day, week

  • date_from: UTC timestamp. Example: 2023-01-10

  • date_till: UTC timestamp. Example: 2023-01-10

  • day_of_week: mon, tue, wed, thu, fri, sat, sun

  • control_hours_from: Example: 08:00:00, minutes and seconds are truncated

  • control_hours_till:Example: 21:00:00, minutes and seconds are truncated

  • project_id: One or many project IDs.

  • zone_id: One or many zone IDs.

  • group_id: One or many group IDs.

  • group_custom_id: One or many group custom IDs.

  • floor_number: one or many floor numbers

  • level_id: One or many level IDs. Pass 0 to select groups out of level (directly in the zone).

  • order_by: Specify the ordering key.

    • Allowed values: name, occupied

    • Default: name

  • order_direction: Specify the ordering direction.

    • Allowed values: asc, desc

    • Default: asc

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.

Example:

Request history of average occupancy and in/out traffic statistics of a zone with ID 123 between July 12, 2021, and July 13, 2021, with aggregating data by 6 hours periods:

Response:

As shown in the screenshot at the top of the page, this endpoint provides data that is suitable for both the Utilization History chart and the Traffic In|Out History chart. The API response includes a list of objects, with each object containing information about the parking hierarchy level (project/zone/level/group), the chosen grouping parameter (grouped_by), the grouping interval (grouped_by_interval), a timestamp (datetime), and occupancy data.

Here's a breakdown of the key fields in the API response:

  • project/zone/level/group: This field describes the parking hierarchy object that has been selected for grouping based on the group_by query argument.

  • grouped_by: Indicates the value of the group_by query argument, which determines how the data is grouped.

  • grouped_by_interval: Specifies the value of the group_by_interval query argument, which defines the time interval for grouping.

  • datetime: Represents the timestamp associated with the data entry.

  • utilization: Indicates the average utilization rate, ranging from 0.00 to 1.00, for the specified period.

  • occupied: Represents the number of occupied parking positions during the specified period.

  • traffic_in: Indicates the number of vehicles that entered during the specified period.

  • traffic_out: Represents the number of vehicles that exited during the specified period.

This data structure allows you to analyze and visualize parking utilization, traffic flow, and occupancy trends over time.

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

Utilization Heatmap API

  • URL: https://api.nwave.io/analytics/v1/car_counters/history/heatmap

  • Method: GET

Query Arguments:

  • group_by: Group results by project, zone, level, or group.

    • Allowed values: project, zone, group, level

  • group_by_interval:

    • Available values : 5m, 10m, 15m, 20m, 30m, hour, 2h, 3h, 4h, 6h, 12h, day, week

  • date_from: UTC timestamp. Example: 2023-01-10

  • date_till: UTC timestamp. Example: 2023-01-10

  • day_of_week: mon, tue, wed, thu, fri, sat, sun

  • control_hours_from: Example: 08:00:00, minutes and seconds are truncated

  • control_hours_till:Example: 21:00:00, minutes and seconds are truncated

  • project_id: One or many project IDs.

  • zone_id: One or many zone IDs.

  • group_id: One or many group IDs.

  • group_custom_id: One or many group custom IDs.

  • floor_number: one or many floor numbers

  • level_id: One or many level IDs. Pass 0 to select groups out of level (directly in the zone).

  • order_by: Specify the ordering key.

    • Allowed values: name, id, occupied, utilization, week_day, time

    • Default: name

  • order_direction: Specify the ordering direction.

    • Allowed values: asc, desc

    • Default: asc

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.

Example:

Request occupancy heatmap of a zone with ID 123 between July 12, 2021, and August 11, 2021 with aggregating data by daily periods:

Response:

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