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

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

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

Objects/Types

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

Location

Project Occupancy

Zone Occupancy

Level Occupancy

Group Occupancy

Position Occupancy

Create Subscription Response

Occupancy Snapshot

Subscription Occupancy Snapshot

Subscription Occupancy Updates

Enums

Check Consistency

Group By

Labels Match

Occupancy Status

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.

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.

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!

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

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.

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

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.

mutation {
  demandSubscriptionOccupancySnapshot(id: "12345")
}

Keep Alive Subscirption

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

mutation {
  keepAliveSubscription(id: "12345") {
    id
    expiresOn
  }
}

GraphQL Schema