GraphQL Occupancy API offers similar functionality to REST Occupancy API, however, there are additional benefits to using GraphQL.

You can select the fields you want to receive from the API. By requesting only the required fields from the API you can decrease traffic and consequently increase load speed.

Additionally, GraphQL Occupancy API supports subscriptions, which allows you to receive real-time occupancy updates.

Authorization

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

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

Object & Field Descriptions

PositionOccupancy - describes a position and its occupancy state

• SubscriptionArea - special object for describing occupancy states changes for some area

  • id - area id

  • location - object containing latitude and longitude coordinates

  • radius - area’s radius in meters

  • granularity - user-defined type for returned objects. Available values: [Position, Level, Group, Zone]

  • updates - list of Occupancy objects. Type of objects depends on the selected granularity option.

  • updateTime - the time of last occupancy status update

Documentation

The following GraphQL schema describes data types and operations that can be performed.

GraphQL Schema

The following GraphQL schema describes data types and operations that can be performed.

type GroupOccupancy @aws_api_key
@aws_lambda {
	id: ID!
	zoneId: Int
	levelId: Int
	name: String!
	groupType: String!
	customId: String
	location: Location
	positionsOccupancy: [PositionOccupancy]
	summary: OccupancySummary
}

input GroupOccupancyInput {
	id: ID!
	zoneId: Int
	levelId: Int
	name: String!
	groupType: String!
	customId: String
	location: LocationInput!
	positionsOccupancy: [PositionOccupancyInput!]!
	summary: OccupancySummaryInput!
}

type LevelOccupancy @aws_api_key
@aws_lambda {
	id: Int
	name: String
	zoneId: Int!
	floorNumber: Int
	summary: OccupancySummary
}

input LevelOccupancyInput {
	id: Int
	zoneId: Int!
	floorNumber: Int
	name: String
	summary: OccupancySummaryInput!
}

type Location @aws_api_key
@aws_lambda {

	lat: Float!

	lon: Float!
}

input LocationInput {
	lat: 

Float!
	lon: Float!
}

enum 

OccupancyStatus {
	Occupied
	Free
}

type OccupancySummary 

@aws_api_key
@aws_lambda {

	total: Int!

	occupied: Int!

	available: Int!

	undefined: Int!
}

input OccupancySummaryInput {

	total: Int!

	occupied: Int!

	available: Int!

	undefined: Int!
}

type PositionOccupancy 

@aws_api_key
@aws_lambda {

	id: 

ID!

	customId: String

	groupId: Int

	occupancyStatus: OccupancyStatus

	statusChangeTime: AWSDateTime

	location: Location!
	labels: [String]
}

input PositionOccupancyInput {

	id: 

ID!

	customId: String

	groupId: Int!

	occupancyStatus: OccupancyStatus!

	statusChangeTime: AWSDateTime!

	location: LocationInput!
	labels: [String]
}

union RtaUpdateObject = ZoneOccupancy | LevelOccupancy | GroupOccupancy 

| PositionOccupancy 

interface SubscriptionArea {
	id: 

ID!
	location: Location
	radius: Int
	zoneId: [Int]

	levelId: [Int]
	floorNumber: [Int]
	groupId: [Int]

	labels: [String

]
	granularity: 

SubscriptionGranularity!
	expiresOn: 

AWSDateTime!
}

type SubscriptionAreaNoUpdates 

implements 

SubscriptionArea @aws_api_key
@aws_lambda {
	id: ID!
	location: Location
	radius: Int
	zoneId: [Int]
	levelId: [Int]
	floorNumber: [Int]

	groupId: [

Int]
	labels: [String]
	granularity: SubscriptionGranularity!

	expiresOn: 

AWSDateTime!
}

type 

SubscriptionAreaWithUpdates 

implements SubscriptionArea @aws_api_key
@aws_lambda {
	id: 

ID!
	location: Location

	radius: Int
	zoneId: [Int]
	levelId: [Int]
	floorNumber: [Int]

	groupId: [Int]
	labels: [String]
	granularity: SubscriptionGranularity!

	expiresOn: 

AWSDateTime!
	updates: 

[RtaUpdateObject]
	updateTime: 

AWSDateTime
}

enum SubscriptionGranularity 

{

	Position
	Level
	Group
	Zone
}

type ZoneOccupancy @aws_api_key
@aws_lambda {

	id: 

ID!
	name: String!
	projectId: Int
	summary: 

OccupancySummary
}

input ZoneOccupancyInput {

	id: 

ID!
	name: String

!

	projectId: Int

	summary: 

OccupancySummaryInput!
}

type 

Mutation {
	createSubscriptionArea(
		lat: 

Float,
		lon: 

Float,
		radius: Int,
		zoneId: [Int

],
		levelId: [Int],
		floorNumber: [Int],
		groupId: 

[Int],
		labels: [String],
		granularity: SubscriptionGranularity

	): 

SubscriptionAreaNoUpdates
		@aws_api_key
@aws_lambda

	updateSubscriptionArea(
		id: 

ID!,

		lat: Float,
		lon: Float,
		radius: Int,
		zoneId: [Int],
		levelId: [Int],
		floorNumber: [Int],
		groupId: [Int],
		labels: [String],
		granularity: SubscriptionGranularity
	): SubscriptionAreaNoUpdates
		@aws_api_key
@aws_lambda
	updatePositionOccupancy(positionId: Int!, occupancyStatus: OccupancyStatus!, timestamp: String!): PositionOccupancy
		@aws_api_key
	pushPositionUpdates(
		id: ID!,
		location: LocationInput,
		radius: Int,
		zoneId: [Int],
		levelId: [Int],
		floorNumber: [Int],
		groupId: [Int],
		labels: [String],
		granularity: SubscriptionGranularity!,
		expiresOn: AWSDateTime!,
		updates: [PositionOccupancyInput!]!,
		updateTime: String!
	): SubscriptionAreaWithUpdates
		@aws_api_key
	pushGroupUpdates(
		id: ID!,
		location: LocationInput,
		radius: Int,
		zoneId: [Int],
		levelId: [Int],
		floorNumber: [Int],
		groupId: [Int],
		labels: [String],
		granularity: SubscriptionGranularity!,
		expiresOn: AWSDateTime!,
		updates: [GroupOccupancyInput!]!,
		updateTime: String!
	): SubscriptionAreaWithUpdates
		@aws_api_key
	pushLevelUpdates(
		id: ID!,
		location: LocationInput,
		radius: Int,
		zoneId: [Int],
		levelId: [Int],
		floorNumber: [Int],
		groupId: [Int],
		labels: [String],
		granularity: SubscriptionGranularity!,
		expiresOn: AWSDateTime!,
		updates: [LevelOccupancyInput!]!,
		updateTime: String!
	): SubscriptionAreaWithUpdates
		@aws_api_key
	pushZoneUpdates(
		id: ID!,
		location: LocationInput,
		radius: Int,
		zoneId: [Int],
		levelId: [Int],
		floorNumber: [Int],
		groupId: [Int],
		labels: [String],
		granularity: SubscriptionGranularity!,
		expiresOn: AWSDateTime!,
		updates: [ZoneOccupancyInput!]!,
		updateTime: String!
	): SubscriptionAreaWithUpdates
		@aws_api_key
}

type Query {

	groupOccupancy(id: 

ID!): GroupOccupancy
		@aws_api_key
@aws_lambda

	findGroupOccupancies(

		ids: [Int]

,
		lat: Float

,
		lon: Float,
		radius: 

Int,
		levelId: [Int

!],
		labels: [

String!]

,
		floorNumber: [Int!]

,
		zoneId: [Int!]

,
		projectId: Int

,
		groupCustomId: String

,
		limit: Int,

		offset: Int
	): [GroupOccupancy]
		@aws_api_key
@aws_lambda

	findPositionOccupancies(

		ids: [Int]

,
		lat: Float

,
		lon: Float

,
		radius: Int

,
		groupId: [Int!],

		levelId: [Int!],
		labels: [

String!]

,
		floorNumber: [Int!]

,
		zoneId: [Int!]

,
		projectId: Int

,
		groupCustomId: String

,
		limit: Int

,
		offset: Int

	): [PositionOccupancy]
		@aws_api_key
@aws_lambda
}

type 

Subscription {
	onSubscriptionAreaUpdates(id: ID!): SubscriptionAreaWithUpdates
		@aws_api_key

@aws_lambda
@aws_subscribe(mutations: ["pushPositionUpdates","pushGroupUpdates","pushLevelUpdates","pushZoneUpdates"])
}

# @api_key (admin) auth and @aws_lambda (user) auth are required for all types apart from:
##   updatePositionOccupancy
##   pushPositionUpdates
##   pushGroupUpdates
##   pushLevelUpdates
##   pushZoneUpdates
## These are for internal subscription notification and should have exclusive admin access
schema {
	query: Query
	mutation: Mutation
	subscription: Subscription
}

Subscription Areas

A subscription area is an object that has two main functions:

1. Filtering of the incoming position updates

2. Defining the format of updates that is received by subscribers

There are two types defined in the GraphQL schema for Subscription Areas:

SubscriptionAreaNoUpdates - this type is returned when you create or update a Subscription Area. It does not have ‘updates’ & ‘updateTime’ fields as updates are only returned to active subscriptions.

SubscriptionAreaWithUpdates - this type is returned to subscribers and as the name suggests it contains the ‘updates’ & ‘updateTime’ fields.

Subscription Area Filters

Subscription Areas filter the incoming updates and only notify the subscribers if the incoming position update matches all of the filters. Subscription Area filters can also be split into 2 categories:

1. Hierarchical Filters: zoneId, groupId, levelId, floorNumber, labels

2. Geospatial Filters: lat, lon, radius

A match is when all position attributes are a subset (⊆) of the Subscription Area filters and it implies that a given position is inside a Subscription Area.

The following example is a valid match between Subscription Area and Position Update.

Subscription Area Updates

The updates field of a Subscription Area can contain a list of 4 different types. All types within the updates list are the same. The type you will receive in the updates field depends on the granularity you choose.

Object & Field Descriptions

SubscirptionArea

• id - subscription area id

• location - center coordinates of the search area

• radius - radius from the center in meeters that creates the search area

• zoneId - list of zone ids to match

• levelId - list of level ids to match

• floorNumber - list of floor numbers to match

• groupId - list of group ids to match

• labels - list of labels to match

• granularity - defines the updates type

• expiresOn - timestamp of subscription area expiration

• udpates - occupancy updates for a subscription area

• updateTime - timestamp of the occupancy update

ZoneOccupancy

• id - zone id

• name - zone name

• projectId - project id

• summary - summary of occupancies in the Zone

LevelOccupancy

• id - level id

• name - level name

• zoneId - zone id

• floorNumber - floor number of a level

• summary - summary of occupancies on a Level

GroupOccupancy

• id - group id

• zoneId - zone id

• levelId - level id

• name - group name

• groupType - group type e.g. marked_bay

• customId - user defined group id

• location - сenter coordinates of a group

• positionOccupancy - list of PositionOccupancy objects for a group

• summary - summary of occupancies in the Group

PositionOccupancy

• id - position id

• customId - custom id

• groupId - group id

• occupancyStatus - ‘occupied’, ‘free’ or null

• statusChangeTime - timestamp of last occupancyStatus change

• location: coordinates of a position

Operations

The following operations can be performed using either Postman or curl command except for subscription operations.

groupOccupancy

This query will return the occupancy of a single group.

findGroupOccupancies

This query will return a list of group occupancies.

findPositionOccupancies

This query will return a list of position occupancies.

findGroupOccupancies

This query will return a list of group occupancies.

createSubscriptionArea

This mutation will create a new subscription area.

Subscription Area Expiration

By default, subscription areas expire 5 minutes after creation. Once a subscription area is expired, it cannot be extended and subscribers will stop receiving updates.

findPositionOccupancies

This query will return a list of position occupancies.

onSubscriptionAreaUpdates

This subscription will subscribe to occupancy updates inside an area.

Selected updates object type must correspond to the granularity of the created search area:

1. granularity: Position → updates { … on PositionOccupancy }

2. granularity: Group → updates { … on GroupOccupancy }

If you are unsure of the granularity for your subscription area, you can specify both types inside the updates.

createSubscriptionArea

This mutation will create a new subscription area.

Subscription Area Expiration

By default, subscription areas expire 5 minutes after creation. Once a subscription area is expired, it cannot be extended and subscribers will stop receiving updates.

onSubscriptionAreaUpdates

This subscription will subscribe to occupancy updates inside an area.

Selected updates object type must correspond to the granularity of the created search area:

1. granularity: Position → updates { … on PositionOccupancy }

2. granularity: Group → updates { … on GroupOccupancy }

If you are unsure of the granularity for your subscription area, you can specify both types inside the updates.

updateSubscriptionArea

This mutation will update an existing subscription area.

Use cases

query MyQuery {
  findGroupOccupancies(
    

updateSubscriptionArea

This mutation will update an existing subscription area.

occupancyStatus
  }
}

Use cases

Displaying occupancy statuses of positions with label “Disabled” within 2km radius

Code Block language graphql

query

mutation

MyQuery

MyMutation {

findGroupOccupancies

createSubscriptionArea(

lat

granularity:

0.0

Position,

lon

lat:

0

1.

0

5,

radius: 2000 ) { location {

lon: 1.5, radius: 2000

lat

) {

lon

id } } subscription

MySubscription

summary

{ onSubscriptionAreaUpdates( id:

available

<id from previous mutation>

}

)

}

} InfoThe summary object should be used to display availability for all parking group types

Displaying

all

live parking

groups

statuses within 2km

in a mobile appImage Removed

radius

Code Block language graphql

query MyQuery { groupOccupancy(id: 1) { positionsOccupancy {

mutation LevelOccuppancyMutation {

location

createSubscriptionArea(

{

zoneId: 3,

lat

granularity: Level ) {

lon

id } } subscription MySubscription { onSubscriptionAreaUpdates(

occupancyStatus

id: <id from previous

}

mutation>

}

) }	Displaying

individual parking positions when a user approaches his desired parking locationImage Removed

live occupancies per level in a zone (multistory car park) Image Added

Code Block language graphql mutation

MyMutation

LevelOccuppancyDisabledMutation { createSubscriptionArea(

granularity

zoneId:

Position

3,

lat

labels:

1.5

"Disabled",

lon

granularity:

1.5, radius: 2000

Level ) { id } } subscription MySubscription { onSubscriptionAreaUpdates( id: <id from previous mutation> ) }

Displaying live

parking statuses within 2km radius

occupancies of disabled spaces per level in a zone Image Added
Code Block language graphql mutation MyMutation { updateSubscriptionArea( id: 1, ) { expiresOn id } }	Extend subscription area expiration

Postman Collection

Download Postman Collection here:

Importing Collection

1. Click import in My Workspace section.

1. Upload the collection file and click

Import.

Adding API key to Postman Environment

This collection uses the api_key variable to add an authorization token to the x-api-key header.

1. To create a new environment click on the eye icon near the top right corner.

2. Click Add to add a new environment.

3. Add the gql_api_key variable name and your token in the initial value.

4. Select the New Environment from the list.

5. You can now test the requests in the GraphQL Occupancy Collection.

Example Python Client

There is a simple GraphQL client example in our Github repository. It is developed in Python and let you start getting data on demand and subscribe on occupancy change notifications.

Please, follow the instructions in the README.md to prepare your invironment for running example.

https://github.com/nwaveio/graphql_occupancy_example