Versions Compared

Old Version 46

changes.mady.by.user Evgeny Aleshin

Saved on

compared with

New Version 47

changes.mady.by.user Evgeny Aleshin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
stylenone

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

Authorization

<your token>

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

Note

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

Info

This API is available at the following url:

Code Block
languagebash
https://occupancy.api.nwave.io/graphql

Request Types

Enums

OccupancyStatus

Code Block
languagegraphql
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

Code Block
languagegraphql
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

Code Block
languagegraphql
enum GroupBy {
  project
  zone
  level
  group
  position
}

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

Code Block
languagegraphql
enum CheckConsistency {
  hierarchy
}

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

Code Block
languagegraphql
input LocationWithRadiusInput {
  distanceMeters: Int!
  latitude: Float!
  longitude: Float!
}

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

Code Block
languagegraphql
input FilterInput {
  id: ID!
  area: LocationWithRadiusInput
  projectId: [Int!]
  zoneId: [Int!]
  levelId: [Int!]
  groupId: [Int!]
  groupCustomId: [String!]
  networkId: [String!]
  labels: [String!]
  labelsMatch: LabelsMatch
  floorNumber: [Int!]
  groupBy: GroupBy
}

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

Code Block
languagegraphql
type Location {
    lat: Float!
    lon: Float!
}

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

Code Block
languagegraphql
type OccupancySummary {
    total: Int
    occupied: Int
    available: Int
    undefined: Int
}

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)

Info

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

Code Block
languagegraphql
type ProjectOccupancy {
    id: ID!
    name: String
    location: Location
    occupancy: OccupancySummary!
}

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

Code Block
languagegraphql
type ZoneOccupancy {
    id: ID!
    name: String
    projectId: String!
    location: Location
    occupancy: OccupancySummary!
}

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

Code Block
languagegraphql
type LevelOccupancy {
    id: ID!
    name: String
    zoneId: Int!
    projectId: Int!
    floorNumber: Int
    occupancy: OccupancySummary!
}

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

Code Block
languagegraphql
type GroupOccupancy {
    id: ID!
    projectId: Int!
    zoneId: Int!
    levelId: Int!
    name: String
    groupType: String!
    customId: String
    locations: [Location!]!
    occupancy: OccupancySummary!
}

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

Code Block
languagegraphql
type PositionOccupancy {
    id: ID!
    customId: String
    groupId: Int!
    zoneId: Int!
    levelId: Int!
    projectId: Int!
    occupancyStatus: OccupancyStatus!
    statusChangeTime: AWSDateTime
    location: Location!
    labels: [String!]
}

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

Code Block
languagegraphql
type CreateSubscriptionResponse {
  id: ID!
  expiresOn: AWSDateTime!
}

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

Code Block
languagegraphql
type OccupancySnapshot {
  id: ID!
  projects: [ProjectOccupancy!]
  zones: [ZoneOccupancy!]
  levels: [LevelOccupancy!]
  groups: [GroupOccupancy!]
  positions: [PositionOccupancy!]
  occupancy: OccupancySummary
}

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

Code Block
languagegraphql
type SubscriptionOccupancySnapshot {
  id: ID!
  time: AWSDateTime!
  filters: [OccupancySnapshot!]!
}

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

Code Block
languagegraphql
type SubscriptionOccupancyUpdates {
  id: ID!
  time: AWSDateTime!
  project: ProjectOccupancy
  zone: ZoneOccupancy
  level: LevelOccupancy
  group: GroupOccupancy
  position: PositionOccupancy
}

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

Example use case: A parking management company uses a centralized dashboard to monitor parking occupancy across multiple projects and locations. The dashboard provides a global view of parking availability and usage statistics, helping the company analyze trends, optimize capacity, and make informed decisions on pricing or resource allocation. The query retrieves occupancy data for multiple projects, showing total, available, and occupied spaces.

Code Block
languagegraphql
findProjectOccupancies(
  id: [Int!],
  lat: Float,
  lon: Float,
  distanceMeters: Int,
  networkId: [String!],
  groupId: [Int!],
  levelId: [Int!],
  labels: [String!],
  labelsMatch: LabelsMatch,
  floorNumber: [Int!],
  zoneId: [Int!],
  groupCustomId: [String!],
  limit: Int = 100,
  offset: Int = 0
): [ProjectOccupancy]
Code Block
languagegraphql
{
  findProjectOccupancies(
    projectId: [101, 202, 303]
  ) {
    id
    name
    location {
      lat
      lon
    }
    occupancy {
      total
      available
      occupied
    }
  }
}

Zone Queries

Example use case: A mobile app helps drivers find available parking zones near their current location. The app allows users to specify the maximum distance from their location and shows the available parking spaces in nearby zones.

Code Block
languagegraphql
findZoneOccupancies(
  id: [Int!],
  lat: Float,
  lon: Float,
  distanceMeters: Int,
  networkId: [String!],
  groupId: [Int!],
  levelId: [Int!],
  labels: [String!],
  labelsMatch: LabelsMatch,
  floorNumber: [Int!],
  projectId: [Int!],
  groupCustomId: [String!],
  limit: Int = 100,
  offset: Int = 0
): [ZoneOccupancy]
Code Block
languagegraphql
{
  findZoneOccupancies(
    lat: 37.7749,
    lon: -122.4194,
    distanceMeters: 5000,
  ) {
    name
    location {
      lat
      lon
    }
    occupancy {
      available
    }
  }
}

Level Queries

Example use case: A parking facility is equipped with digital signage to help drivers locate available parking spaces on different levels. The digital signage system periodically queries the parking management system to retrieve the latest occupancy data for each level and displays the number of available spots on each floor. The system filters by specific zone and project IDs to ensure it only retrieves data for relevant sections of the parking facility.

Code Block
languagegraphql
findLevelOccupancies(
  id: [Int!],
  lat: Float,
  lon: Float,
  distanceMeters: Int,
  networkId: [String!],
  groupId: [Int!],
  labels: [String!],
  labelsMatch: LabelsMatch,
  floorNumber: [Int!],
  zoneId: [Int!],
  projectId: [Int!],
  groupCustomId: [String!],
  limit: Int = 100,
  offset: Int = 0
): [LevelOccupancy]
Code Block
languagegraphql
{
  findLevelOccupancies(
    zoneId: [5],
    projectId: [101],
    floorNumber: [1, 2, 3],
  ) {
    id
    name
    floorNumber
    occupancy {
      total
      available
      occupied
    }
  }
}

Group Queries

Example use case: A city has implemented digital signage to guide drivers to available EV parking spots in outdoor street parking zones. The system uses parking occupancy data filtered for groups of EV-designated spots and displays the availability on signage near high-traffic areas. This reduces emissions by minimizing the time drivers spend searching for EV parking, thus supporting the city’s environmental goals.

Code Block
languagegraphql
findGroupOccupancies(
  id: [Int!],
  lat: Float,
  lon: Float,
  distanceMeters: Int,
  networkId: [String!],
  levelId: [Int!],
  labels: [String!],
  labelsMatch: LabelsMatch,
  floorNumber: [Int!],
  zoneId: [Int!],
  projectId: [Int!],
  groupCustomId: [String!],
  limit: Int = 100,
  offset: Int = 0
): [GroupOccupancy]
Code Block
languagegraphql
{
  findGroupOccupancies(
    labels: ["EV"],
    labelsMatch: any,
    zoneId: [10, 22],
  ) {
    id
    name
    groupType
    locations {
      lat
      lon
    }
    occupancy {
      total
      available
      occupied
    }
  }
}

Position Queries

Example use case: A mobile app is designed to help drivers locate and navigate to individual parking spots within a parking facility. The app displays a map that shows the exact location of available parking spaces and guides the driver to the nearest free spot. The query retrieves data for individual parking positions, including their occupancy status and location, allowing the app to highlight available spaces on the map.

Code Block
languagegraphql
findPositionOccupancies(
  id: [String!],
  lat: Float,
  lon: Float,
  distanceMeters: Int,
  groupId: [Int!],
  levelId: [Int!],
  labels: [String!],
  labelsMatch: LabelsMatch,
  floorNumber: [Int!],
  zoneId: [Int!],
  projectId: [Int!],
  groupCustomId: [String!],
  limit: Int = 100,
  offset: Int = 0
): [PositionOccupancy]
Code Block
languagegraphql
{
  findPositionOccupancies(
    lat: 40.7128,
    lon: -74.0060,
    distanceMeters: 500,
    labels: ["EV"],
    labelsMatch: any,
    zoneId: [7]
  ) {
    id
    location {
      lat
      lon
    }
    occupancyStatus
    statusChangeTime
  }

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

Info

The subscription expiry time is automatically extended after each update. To extend a subscription without changing its parameters you should use the keepAliveSubscription mutation.

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.

Code Block
languagegraphql
createSubscriptionOccupancySnapshot(
  filters: [FilterInput!]!,
  checkConsistency: [CheckConsistency!]
): CreateSubscriptionResponse!
Code Block
languagegraphql
mutation {
  createSubscriptionOccupancySnapshot(
    filters: [{
      projectId: [101],
      zoneId: [10, 11],
      area: {
        latitude: 37.7749,
        longitude: -122.4194,
        distanceMeters: 5000
      },
      labels: ["EV"],
      labelsMatch: any,
      groupBy: zone
    }]
  ) {
    id
    expiresOn
  }
}

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.

Code Block
languagegraphql
createSubscriptionOccupancyUpdates(
  projectId: [Int!],
  zoneId: [Int!],
  levelId: [Int!],
  floorNumber: [Int!],
  groupId: [Int!],
  groupCustomId: [String!],
  networkId: [String!],
  labels: [String!],
  labelsMatch: LabelsMatch,
  area: LocationWithRadiusInput,
  groupBy: GroupBy!,
  checkConsistency: [CheckConsistency!]
): CreateSubscriptionResponse!
Code Block
languagegraphql
mutation {
  createSubscriptionOccupancyUpdates(
    projectId: [101],
    zoneId: [10, 11],
    area: {
      latitude: 37.7749,
      longitude: -122.4194,
      distanceMeters: 5000
    },
    labels: ["EV"],
    labelsMatch: any,
    groupBy: zone
  ) {
    id
    expiresOn
  }
}

Subscription Updates Warning

Note

Important: Sending an empty update will result in clearing all subscription parameters, which may disrupt the functionality of the subscription. Always ensure to include the full set of original parameters when extending or modifying a subscription to avoid unintended data loss or disruptions.

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.

Code Block
languagegraphql
mutation {
  updateSubscriptionOccupancySnapshot(
    id: "12345",
    filters: [{
      projectId: [101],
      zoneId: [10, 11],
      area: {
        latitude: 37.7749,
        longitude: -122.4194,
        distanceMeters: 1000  # Updated
      },
      labels: ["EV"],
      labelsMatch: any,
      groupBy: position  # Updated
    }]
  ) {
    id
    expiresOn
  }
}

Update Updates Subscription

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

Code Block
languagegraphql
mutation {
  updateSubscriptionOccupancyUpdates(
    id: "12345",
    projectId: [101],
    zoneId: [10, 11],
    area: {
      latitude: 37.7749,
      longitude: -122.4194,
      distanceMeters: 1000
    },
    labels: ["EV"],
    labelsMatch: any,
    groupBy: position
  ) {
    id
    expiresOn
  }
}

Demand Snapshot

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

Code Block
languagegraphql
mutation {
  demandSubscriptionOccupancySnapshot(id: "12345")
}

Keep Alive Subscirption

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

Code Block
languagegraphql
mutation {
  keepAliveSubscription(id: "12345") {
    id
    expiresOn
  }
}

GraphQL Schema

View file
nameschema.graphql