GraphQL Occupancy API V2

Owned by Evgeny Aleshin
Last updated: yesterday at 7:57 pm
20 min read

Overview

This document outlines the GraphQL Occupancy API V2, which uses the Occupancy Aggregator service. Key updates include support for zone and floor queries, label aggregation, hybrid parking types, and two types of real-time subscriptions. The API is designed for efficient real-time parking space data retrieval and management, supporting various use cases from individual space monitoring to group and zone-level occupancy tracking.

Authorization

In order to authorize with this API, you need to add the following header to your request:

Key

Value

Key

Value

Authorization

<your token>

Your token can be obtained from the Company Info section of the Nwave’s console.

You are not able to make API calls more frequently, than 300 times per 5 minutes with the same token. If amount of requests exceeds the limit, API reponds with error until the end of the 5 minute interval.

Endpoint Url

This API is available at the following url:

https://occupancy.api.nwave.io/graphql

 

Request Types

Enums

OccupancyStatus

enum OccupancyStatus { Free Occupied Undefined }

Represents the current state of a parking space:

  • Free: Space is available for parking

  • Occupied: Space is currently in use

  • Undefined: Status cannot be determined (e.g., sensor malfunction or missing data)

LabelsMatch

enum LabelsMatch { all any exclude }

Defines how multiple label filters should be applied when searching for parking spaces:

  • all: Space must have all specified labels

  • any: Space must have at least one of the specified labels

  • exclude: Space must not have any of the specified labels

GroupBy

Specifies the hierarchical level at which to aggregate parking data:

  • project: Aggregate across entire projects

  • zone: Aggregate by zones

  • level: Aggregate by floor/level

  • group: Aggregate by parking space groups

  • position: Show individual parking spaces

CheckConsistency

Controls validation of hierarchical relationships in queries:

  • hierarchy: Ensures entities exist within their parent containers (e.g., zones within projects, groups within zones)

Input Types

LocationWithRadiusInput

Defines a circular geographical area by specifying a center point and radius. Used for location-based filtering of parking data.

Fields:

  • latitude: The latitude coordinate of the center point

  • longitude: The longitude coordinate of the center point

  • distanceMeters: The radius of the circular area in meters, defining how far from the center point to include results

FilterInput

Provides comprehensive filtering capabilities for querying parking occupancy data.

Fields:

 

Response Types

Core Types

Core types form the foundation of the occupancy API, with Location being used to position elements geographically and OccupancySummary providing the essential metrics needed to understand parking availability at any level of the system hierarchy.

Location

Represents a geographical coordinate point used throughout the API to specify positions of parking facilities, zones, spaces and other physical elements in the system.
Fields:

  • lat: The latitude coordinate of the location point

  • lon: The longitude coordinate of the location point

OccupancySummary

Provides statistical information about parking space occupancy. It is used across different hierarchy levels (projects, zones, levels, groups) to give an overview of parking space utilization and availability.
Fields:

  • total: The total number of parking spaces in the scope

  • occupied: The number of parking spaces currently in use

  • available: The number of parking spaces currently available for use

  • undefined: The number of parking spaces whose status cannot be determined (e.g., no sensor in position or device error)

When handling parking space availability, it is recommended to treat spaces with undefined OccupancyStatus as occupied to avoid potential space conflicts and ensure better user experience.

Hierarchical Types

ProjectOccupancy

Represents the highest level in the parking facility hierarchy, typically encompassing an entire parking facility or a collection of parking areas managed as a single entity. It provides aggregated occupancy data for all parking spaces within the project.

Fields:

  • id: Unique integer identifier for the project

  • name: Human-readable name of the parking project

  • location: Geographic coordinates representing the project's central location point

  • occupancy: Aggregated statistics showing total spaces, occupied spaces, available spaces, and undefined statuses across the entire project

ZoneOccupancy

Represents a distinct area within a parking facility that contains multiple parking spaces. Zones help organize parking facilities into logical sections and provide aggregated occupancy data for their contained spaces.

Fields:

  • id: Unique integer identifier for the zone

  • name: Human-readable name for the zone (e.g., "South Garage")

  • projectId: Reference to the parent project containing this zone

  • location: Geographic coordinates representing the central point of the zone

  • occupancy: Statistical summary of parking space availability within the zone

LevelOccupancy

Represents a floor or level within a parking facility, providing occupancy data for a specific vertical section of the facility. This type is particularly useful for multi-story parking structures where understanding availability per floor is important for navigation and space allocation.

Fields:

  • id: Unique integer identifier for the level

  • name: Human-readable name for the level (e.g., "Ground Floor", "Level C")

  • zoneId: Reference to the parent zone containing this level

  • projectId: Reference to the parent project containing this level

  • floorNumber: Numeric representation of the floor level within the structure

  • occupancy: Statistical summary of parking space availability on this level

GroupOccupancy

Represents a collection of related parking spaces within a level, such as designated sections for specific types of vehicles or parking purposes. Groups allow for logical organization of parking spaces and enable targeted monitoring of specialized parking areas.

Fields:

  • id: Unique integer identifier for the group

  • projectId: Reference to the parent project containing this group

  • zoneId: Reference to the parent zone containing this group

  • levelId: Reference to the parent level containing this group

  • name: Human-readable name for the group (e.g., "EV Charging Section", "Row 2A")

  • groupType: Classification of the group's type ('general', 'marked_parking_bay', 'unmarked_parking_bay', 'standalone_car_counters', 'array_car_counters', 'multi_level_parking')

  • customId: Optional external identifier for integration with other systems

  • locations: Array of geographic coordinates defining the physical bounds of the group

  • occupancy: Statistical summary of parking space availability within the group

PositionOccupancy

Represents an individual parking space and its current state. This type provides the most granular level of occupancy data, enabling precise tracking of individual space availability and characteristics.

Fields:

  • id: Unique integer identifier for the parking space

  • customId: Optional external identifier for integration with other systems

  • groupId: Reference to the parent group containing this position

  • zoneId: Reference to the parent zone containing this position

  • levelId: Reference to the parent level containing this position

  • projectId: Reference to the parent project containing this position

  • occupancyStatus: Current state of the parking space (Free/Occupied/Undefined)

  • statusChangeTime: Timestamp of when the occupancy status last changed

  • location: Geographic coordinates of the parking space

  • labels: Array of tags describing characteristics of the space (e.g., "EV", "Disabled", "VIP")

Subscription-Related Types

CreateSubscriptionResponse

Returns the essential information needed to manage real-time data subscriptions. This type is returned by all subscription-related mutations, including creation, updates, and keep-alive operations.

Fields:

  • id: Unique UUID identifier used for referencing this subscription in subsequent operations, including listening for updates and managing the subscription lifecycle

  • expiresOn: Timestamp indicating when the subscription will automatically expire if not renewed

OccupancySnapshot

Represents a complete state capture of parking occupancy data at a specific moment in time. This type provides a hierarchical view of the entire parking system, from individual spaces up to projects, enabling comprehensive analysis of parking availability across all levels of organization.

Fields:

SubscriptionOccupancySnapshot

Represents the response payload for snapshot-based subscriptions, providing complete state information for all entities matching the subscription filters. This type is used when subscribers need comprehensive occupancy data rather than just changes.

Fields:

  • id: Unique UUID identifier linking this update to its subscription

  • time: Timestamp indicating when this snapshot was generated

  • filters: Array of complete occupancy snapshots matching the subscription's filter criteria

SubscriptionOccupancyUpdates

Represents the response payload for update-based subscriptions, providing only changed entities since the last update. The specific field populated in the response corresponds to the groupBy parameter specified during subscription creation (e.g., if groupBy: zone was specified, only the zone field will contain data).

Fields:

  • id: Unique UUID identifier linking this update to its subscription

  • time: Timestamp indicating when this update was generated

  • project: Updated project data when grouping by projects

  • zone: Updated zone data when grouping by zones

  • level: Updated level data when grouping by levels

  • group: Updated group data when grouping by groups

  • position: Updated individual space data when grouping by positions

 

Operations

Queries

In GraphQL, a Query is similar to a GET request in traditional APIs, where the client requests data from the server. Clients can pass query parameters to filter or specify the data they need, making queries customizable and efficient. Each query defines what fields to retrieve, and the server responds with only the requested data.

Project Occupancy Query

Retrieves occupancy information for parking projects matching the specified criteria. This query is particularly useful for applications that need to monitor multiple parking facilities, such as city-wide parking management systems or multi-site parking operators.

Schema

Example Query

Example Response

Zone Occupancy Query

Retrieves occupancy information for parking zones within a specified geographic area. This query is ideal for mobile applications that need to display nearby parking availability to users based on their current location, helping drivers quickly find available parking in their vicinity.

Schema

Example Query

Example Response

Level Occupancy Query

Retrieves occupancy information for specific levels or floors within parking facilities. This query is particularly useful for mobile applications that help users find parking in multi-story structures, enabling them to make informed decisions about which floor to park on before entering the facility.

Schema

Example Query

Example Response

Group Occupancy Queries

Retrieves occupancy information for specific groups of parking spaces. This query is useful for applications that need to monitor specialized parking areas or specific sections within a parking facility.

Schema

Example Request

Example Response

Position Occupancy Query

Retrieves detailed information about individual parking spaces. This query provides the most granular level of parking data, allowing applications to access specific space characteristics and their current state.

Schema

Example Request

Example Response

Mutations and Subscriptions

Subscrption Types

This API enables the creation of subscriptions and provides real-time updates about these subscriptions. There are two types of subscriptions available:

  1. Snapshot Subscriptions: Provide complete occupancy data for the subscribed entities whenever any change occurs.

  2. Update Subscriptions: Provide only the changed occupancy data, making them more efficient for real-time updates.

In GraphQL, a mutation is used to modify or create data on the server, similar to POST, PUT, or DELETE requests in REST APIs. In our use case, mutations are used to create and update subscriptions, allowing clients to manage parking-related subscriptions.

Subscription expiry

Create Snapshot Subscription

Example use case: This mutation creates a subscription to monitor parking availability in zones 10 and 11 within project 101. It uses a zone-based grouping (groupBy: zone) and filters for parking spaces labeled as EV. The subscription is limited to a 5,000-meter radius around the given coordinates (latitude: 37.7749, longitude: -122.4194). The labelsMatch: any ensures that any space marked as EV will be included. The mutation response will include a unique subscription id and an expiresOn field, indicating when the subscription will expire.

Create Updates Subscription

Example use case: When monitoring a large parking facility, receiving only changed data can significantly reduce bandwidth usage. This subscription will only return information about spaces that have changed their occupancy status.

Subscription Updates Warning

Update Snapshot Subscription

Example use case: In this mobile app scenario, the user initially subscribed to parking availability within a 5,000-meter radius, but as they zoom in on the map, the subscription needs to be adjusted to a smaller area.

Update Updates Subscription

Similar to updating snapshot subscriptions, but for the more efficient updates-only subscription

 

Demand Snapshot

Example use case: During testing or debugging, you may need to manually trigger a complete data update.

Keep Alive Subscirption

Extends the expiration time of any subscription without modifying its parameters.

GraphQL Schema

 

Â