GraphQL Occupancy API V2

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, and hybrid parking types. 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.

This API is available at: https://occupancy.api.nwave.io/graphql

1 Authorization
2 Pull API
- 2.1 Objects
  - 2.1.1 Occupancy Summary
  - 2.1.2 Location Object
  - 2.1.3 Project Occupancy
  - 2.1.4 Zone Occupancy
  - 2.1.5 Level Occupancy
  - 2.1.6 Group Occupancy
- 2.2 Queries
  - 2.2.1 Project Queries
  - 2.2.2 Zone Queries
  - 2.2.3 Level Queries
  - 2.2.4 Group Queries
  - 2.2.5 Position Queries
3 Push API
- 3.1 Mutations
  - 3.1.1 Create Subscription
  - 3.1.2 Subscribe
  - 3.1.3 Update Subscription
  - 3.1.4 Demand Subscription
4 GraphQL Schema

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 able to call API not more frequent, than 300 times per 5 minutes interval with use of the same token. If amount of requests exceeds the limit, API reponds with error until the end of 5 minutes interval.

Pull API

Pull API allows you to request data through the API and receive it in full, similar to REST API.

Objects

In GraphQL, an object is a type that defines the structure of data returned by the API. Each field can represent a specific piece of data or a link to other objects. When a client queries the API, they can specify which fields of the object they want to include in the response, allowing for customized and efficient data retrieval.

Occupancy Summary

type OccupancySummary {
    total: Int
    occupied: Int
    available: Int
    undefined: Int
}

The OccupancySummary object provides an overview of parking availability at various levels of the system hierarchy, including Group, Level, Zone, and Project. It summarizes key metrics like the number of available, occupied, and total spaces to give a clear picture of the current usage and capacity at each level.

Location Object

type Location {
    lat: Float!
    lon: Float!
}

The Location object represents the geographical coordinates (latitude and longitude) of a specific point, used to define the position of parking space.

Project Occupancy

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

The ProjectOccupancy object provides a summary of parking availability and usage across an entire project. It includes details about the project's location and name, giving an overall occupancy.

Zone Occupancy

The ZoneOccupancy object gives a summary of parking availability within a specific zone. It includes the zone's location, name, and project association to provide a focused view of parking status within that area.

Level Occupancy

The LevelOccupancy object provides a summary of parking availability on a specific floor or level of a parking facility. It includes identifiers for the level, zone, and project, along with the floor number and occupancy data to give an accurate view of parking status on that level.

Group Occupancy

The GroupOccupancy object provides an overview of parking availability for a group of spaces located on a single level within a zone. It includes a group type and identifiers for the project, zone, and level, along with the specific locations of each position within the group.

Position Occupancy

The PositionOccupancy object represents the real-time occupancy data of a specific parking space, indicating its current availability and when that status last changed. It includes detailed identifiers for its group, zone, level, and project, along with the space’s exact location.

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.

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.

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.

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.

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.

Push API

The Push API enables the creation of subscriptions and provides real-time updates about these subscriptions.

Mutations

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.

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

Subscribe

After creating a new subscription using the createSubscription mutation, you can use the returned subscription ID (e.g., "12345") to activate to that subscription and start receiving real-time occupancy updates whenever there is a change.

Example use case: In a mobile parking app, once a user subscribes to receive updates for available parking spaces in a particular zone or project, the app will continuously monitor changes to the parking occupancy. By subscribing with the updatedSubscriptionOccupancy method, the app can notify the user immediately when a parking spot becomes available or when occupancy changes, providing them with up-to-date information to help them find parking more efficiently.

Update 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. By zooming in, the user is focusing on a more specific region, so the app sends an updateSubscription request to reduce the distanceMeters parameter to 1,000 meters. This ensures that the app only tracks and displays parking spots within the zoomed-in area.

The subscription expiry time is automatically extended after each update. To extend a subscription without changing its parameters, you should send an update request with all the original parameters.

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.

Demand Subscription

Example use case: In a parking management mobile app, the development team is working on debugging the real-time parking availability feature. Typically, the app receives updates about parking space occupancy only when there is a change in availability, such as when a car enters or leaves a space. However, during testing, the development team needs to manually trigger an update to verify that the system is functioning correctly, regardless of whether there has been a recent change in the parking data.