| Table of Contents |
|---|
Authorization
To retrieve occupancy information the client needs to be authorised. To successfully authorize with this API, the client is required to provide a valid authorization token in the x-Auth-Token header of the HTTP request.
The authorization token can be obtained from the Nwave's console.
Click on the user icon in the top right corner and select Company Info.
Click + to the right of the Client API Auth Tokens card to generate a new token.
Enter a name, select permissions and project scope for the new token and click Add.
Copy the generated token.
Endpoints Overview
/group/find/short_info
This endpoint retrieves a list of groups and their occupancy summary per specified filters. Each group info has geolocation location data and filters may be geospatial.
| Info |
|---|
Useful for:
|
Available filters:
project_id
zone_id
group_id
level_id or floor_number
geospatial filter
More detailed info can be found in Swagger documentation in the end of this document.
/group/{group_id}/status
This endpoint retrieves detailed information for a single group. It will return a list of all parking positions, their location and occupancy status. It will also return an occupancy summary for this group.
More detailed info can be found in Swagger documentation in the end of this document.
| Info |
|---|
Useful for quickly displaying all the parking spots in a chosen location. e.g. when a user selects a parking group in a mobile app. |
/positions/states/find
This endpoint retrieves comprehensive information for all of the positions with extensive filtering capabilities.
More detailed info can be found in Swagger documentation in the end of this document.
| Info |
|---|
Useful for finding overstays in a particular zone as it is capable of filtering by occupancy and status change time. |
| Note |
|---|
Thi endpoint can be slower in comparison to /group/find/short_info that returns less data. |
/level/find/short_info
This endpoint retrieves level details and occupancy summary for each level.
More detailed info can be found in Swagger documentation in the end of this document.
| Info |
|---|
Useful for displaying occupancy per level on digital signage. |
/level/{level_id}/status
This endpoint retrieves detailed information for a single level. It will return level details as well as occupancy and location details of every position on that level.
More detailed info can be found in Swagger documentation in the end of this document.
| Info |
|---|
Useful for displaying occupancy of all positions on a single level in a multi-storey car park. |
Quick Start Guide
Sending Requests
cURL
Run the following command in your terminal window.
| Code Block | ||
|---|---|---|
| ||
curl -v -H 'x-Auth-Token: <your_token>' 'https://api.nwave.io/parking/v1/positions/states/find' |
Postman
Enter the URL and select the GET method.
Fill out the key-value pair under the headers tab.
Click Send.
Use Cases
Get Group Information & Occupancy Summary on the 2nd floor of MSCP
Get the list of parking groups objects (including occupancy summary) on the 2nd level of multi-storey car parking (project ID = 123).
| Info |
|---|
This request will return all groups on the 2nd floor and the summary for each group. If you want a summary for the whole floor use level endpoints. |
cURL Example
| Code Block | ||
|---|---|---|
| ||
curl -v -H 'x-Auth-Token: <Your API Key>' 'https://api.nwave.io/parking/v1/group/find/short_info?project=123&floor_number=2' |
Postman Example
Get Group Information & Occupancy Summary within a search radius
Get parking groups within 2km of the user’s coordinates.
cURL example
| Code Block | ||
|---|---|---|
| ||
curl -v -H 'x-Auth-Token: <Your API Key>' 'https://api.nwave.io/parking/v1/group/find/short_info?lat=51.504536284954085&lon=-0.0847326846421401&radius=2000' |
Postman example
Get individual position occupancy & summary for group X
Get detailed group information for group 2100 when a user chooses a group from the map.
cURL example
| Code Block |
|---|
curl -v -H 'x-Auth-Token: <Your API Key>' 'https://api.nwave.io/parking/v1/group/2100/status' |
Postman example
Find occupancies longer than X minutes
If the current time is 2021-02-01 15:24:00, in order to find all positions that have been occupied for over 2 hours in zone 419, we should use the following query string parameters:
state: Occupied
time_to: 2021-04-09T13:24:00 (current time minus 120 minutes)
zone_id: 419
| Info |
|---|
zone id is available on the individual zone page |
cURL example
| Code Block | ||
|---|---|---|
| ||
curl -v -H 'x-Auth-Token: <Your API Key>' 'https://api.nwave.io/parking/v1/positions/states/find?state=Occupied&time_to=2021-02-01T16:00:00&zone_id=123' |
Postman example
Get occupancy summary per level (Digital signage)
To retrieve occupancy summaries for all levels and display them on a digital sign use the following request.
cURL example
| Code Block | ||
|---|---|---|
| ||
curl -v -H 'x-Auth-Token: <Your API Key>' 'https://api.nwave.io/parking/v1/level/find/short_info?zone_id=123' |
Postman example
Get position information and summary for level X (MSCP occupancy map)
Retrieving all of the positions information and summary for a level can be useful for displaying availability map for a single floor in a multi-storey car park.
This request will retrieve:
level information
positions locations on a level
positions' occupancies
occupancy summary for that level
cURL example
| Code Block | ||
|---|---|---|
| ||
curl -v -H 'x-Auth-Token: <Your API Key>' 'https://api.nwave.io/parking/v1/level/130/status' |
Postman example
Postman Collection
| View file | ||
|---|---|---|
|
Importing Collection
Click import in the My Workspace section.
2. 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-Auth-Token header.
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 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 REST Occupancy Collection.
OpenAPI Documentation
| Swagger open api macro | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||
openapi: 3.0.0
servers:
- description: Production Server
url: https://api.nwave.io/parking/v1/
# - description: Development Server
# url: https://devapi.nwave.io/parking/v1/
info:
version: "1.1.0"
title: Parking Interface API
contact:
email: ealeshin@nwave.io
security:
- ApiKey: []
paths:
/group/find/short_info:
get:
tags:
- Groups
summary: Retrieves a list of groups within a given radius and their availability summary
operationId: get_group_short_info
parameters:
- $ref: '#/components/parameters/limit50'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/radius'
- $ref: '#/components/parameters/level_id'
- $ref: '#/components/parameters/floor_number'
- $ref: '#/components/parameters/zone_id'
- $ref: '#/components/parameters/group_id'
- $ref: '#/components/parameters/project_id'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
- message
- reason
- total
properties:
data:
type: array
items:
$ref: '#/components/schemas/ShortInfo'
message:
$ref: '#/components/schemas/message'
reason:
$ref: '#/components/schemas/reason'
total:
$ref: '#/components/schemas/total'
'401':
$ref: '#/components/responses/unauthorised'
'404':
$ref: '#/components/responses/not_found'
options:
tags:
- Groups
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/Empty'
x-amazon-apigateway-integration:
responses:
default:
statusCode: '200'
responseParameters:
method.response.header.Access-Control-Allow-Methods: '''POST,GET,OPTIONS'''
method.response.header.Access-Control-Allow-Origin: '''*'''
method.response.header.Access-Control-Allow-Headers: '''Authorization,Content-Type,X-Amz-Date,X-Amz-Security-Token,X-Api-Key,x-Auth-Token'''
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_match
type: mock
/group/{group_id}/status:
get:
tags:
- Groups
summary: Retrieves a list of parking spots in a given group and their individual availability statuses
operationId: get_group_status
parameters:
- in: path
name: group_id
required: true
schema:
$ref: '#/components/schemas/group_id'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
- message
- reason
properties:
data:
$ref: '#/components/schemas/PositionsAvailability'
message:
$ref: '#/components/schemas/message'
reason:
$ref: '#/components/schemas/reason'
'401':
$ref: '#/components/responses/unauthorised'
'404':
$ref: '#/components/responses/not_found'
options:
tags:
- Groups
parameters:
- in: path
name: group_id
required: true
schema:
$ref: '#/components/schemas/group_id'
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/Empty'
x-amazon-apigateway-integration:
responses:
default:
statusCode: '200'
responseParameters:
method.response.header.Access-Control-Allow-Methods: '''POST,GET,OPTIONS'''
method.response.header.Access-Control-Allow-Origin: '''*'''
method.response.header.Access-Control-Allow-Headers: '''Authorization,Content-Type,X-Amz-Date,X-Amz-Security-Token,X-Api-Key,x-Auth-Token'''
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_match
type: mock
/positions/states/find:
get:
tags:
- Positions
summary: Retrieves detailed position information
operationId: get_position_states
parameters:
- $ref: '#/components/parameters/limit50'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/state'
- $ref: '#/components/parameters/owner_id'
- $ref: '#/components/parameters/device_id'
- $ref: '#/components/parameters/position_id'
- $ref: '#/components/parameters/group_id'
- $ref: '#/components/parameters/zone_id'
- $ref: '#/components/parameters/project_id'
- $ref: '#/components/parameters/network_id'
- $ref: '#/components/parameters/time_from'
- $ref: '#/components/parameters/time_to'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/radius'
- $ref: '#/components/parameters/level_id'
- $ref: '#/components/parameters/floor_number'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
- message
- reason
- total
properties:
data:
$ref: '#/components/schemas/PositionsStatus'
message:
$ref: '#/components/schemas/message'
reason:
$ref: '#/components/schemas/reason'
total:
$ref: '#/components/schemas/total'
'401':
$ref: '#/components/responses/unauthorised'
'404':
$ref: '#/components/responses/not_found'
options:
tags:
- Positions
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/Empty'
x-amazon-apigateway-integration:
responses:
default:
statusCode: '200'
responseParameters:
method.response.header.Access-Control-Allow-Methods: '''POST,GET,OPTIONS'''
method.response.header.Access-Control-Allow-Origin: '''*'''
method.response.header.Access-Control-Allow-Headers: '''Authorization,Content-Type,X-Amz-Date,X-Amz-Security-Token,X-Api-Key,x-Auth-Token'''
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_match
type: mock
/level/{level_id}/status:
get:
tags:
- Levels
summary: Retrieves level status
operationId: get_level_status
parameters:
- in: path
name: level_id
required: true
schema:
$ref: '#/components/schemas/level_id'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
- message
- reason
properties:
data:
$ref: '#/components/schemas/LevelStatus'
message:
$ref: '#/components/schemas/message'
reason:
$ref: '#/components/schemas/reason'
'401':
$ref: '#/components/responses/unauthorised'
'404':
$ref: '#/components/responses/not_found'
options:
tags:
- Levels
parameters:
- in: path
name: level_id
required: true
schema:
$ref: '#/components/schemas/level_id'
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/Empty'
x-amazon-apigateway-integration:
responses:
default:
statusCode: '200'
responseParameters:
method.response.header.Access-Control-Allow-Methods: '''POST,GET,OPTIONS'''
method.response.header.Access-Control-Allow-Origin: '''*'''
method.response.header.Access-Control-Allow-Headers: '''Authorization,Content-Type,X-Amz-Date,X-Amz-Security-Token,X-Api-Key,x-Auth-Token'''
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_match
type: mock
/level/find/short_info:
get:
tags:
- Levels
summary: Retrieves short info for levels
operationId: get_level_short_info
parameters:
- $ref: '#/components/parameters/limit50'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/zone_id'
- $ref: '#/components/parameters/level_id'
- $ref: '#/components/parameters/floor_number'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
- message
- reason
- total
properties:
data:
type: array
items:
$ref: '#/components/schemas/LevelShortInfo'
message:
$ref: '#/components/schemas/message'
reason:
$ref: '#/components/schemas/reason'
total:
$ref: '#/components/schemas/total'
'401':
$ref: '#/components/responses/unauthorised'
'404':
$ref: '#/components/responses/not_found'
options:
tags:
- Levels
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/Empty'
x-amazon-apigateway-integration:
responses:
default:
statusCode: '200'
responseParameters:
method.response.header.Access-Control-Allow-Methods: '''POST,GET,OPTIONS'''
method.response.header.Access-Control-Allow-Origin: '''*'''
method.response.header.Access-Control-Allow-Headers: '''Authorization,Content-Type,X-Amz-Date,X-Amz-Security-Token,X-Api-Key,x-Auth-Token'''
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_match
type: mock
components:
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-Auth-Token
schemas:
total:
description: Total number of records available with the specified filters excluding the pagination
type: integer
format: int32
minimum: 0
group_id:
description: Group ID
type: integer
format: int32
minimum: 0
example: 3092
position_id:
type: integer
format: int32
description: "`Position Primary Key`"
device_id:
type: string
description: "`Device Primary Key`. HEX string"
minLength: 1
maxLength: 7
zone_id:
type: integer
format: int32
description: "`Zone Primary Key`"
custom_id:
type: string
network_id:
type: string
format: uuid
description: "***Position network_id***"
owner_id:
type: integer
format: int32
description: Owner ID from cognito user pool
occupied:
type: boolean
nullable: True
status_time:
description: Timestamp of last change
type: string
format: date-time
example: '2020-01-13T16:15:13.686+00:00'
project_id:
type: integer
format: int32
counter:
type: integer
minimum: 0
multipleOf: 1
format: int32
level_id:
type: integer
format: int32
description: "`Level Primary Key`"
floor_number:
type: integer
format: int32
description: "***Group floor number***"
level_name:
type: string
lat:
type: number
format: float
example: 60.316706
lon:
type: number
format: float
example: 101.622729
message:
type: string
example: 'OK'
reason:
type: string
enum: ['ok', 'created', 'invalid_field', 'no_data', 'not_found', 'not_implemented', 'restricted', 'server_error']
example: 'ok'
Status:
type: object
required:
- device_id
- position_id
- network_id
- group_id
- zone_id
- owner_id
- project_id
- occupied
- status_time
- lat
- lon
properties:
device_id:
$ref: '#/components/schemas/device_id'
position_id:
$ref: '#/components/schemas/position_id'
network_id:
$ref: '#/components/schemas/network_id'
group_id:
$ref: '#/components/schemas/group_id'
zone_id:
$ref: '#/components/schemas/zone_id'
owner_id:
$ref: '#/components/schemas/owner_id'
custom_id:
$ref: '#/components/schemas/custom_id'
project_id:
$ref: '#/components/schemas/project_id'
occupied:
$ref: '#/components/schemas/occupied'
status_time:
$ref: '#/components/schemas/status_time'
lat:
$ref: '#/components/schemas/lat'
lon:
$ref: '#/components/schemas/lon'
level_id:
$ref: '#/components/schemas/level_id'
floor_number:
$ref: '#/components/schemas/floor_number'
PositionsStatus:
type: array
items:
$ref: '#/components/schemas/Status'
LevelStatus:
type: object
required:
- level
- positions_availability
- summary
properties:
level:
$ref: '#/components/schemas/Level'
positions_availability:
type: array
items:
$ref: '#/components/schemas/LevelAvailability'
summary:
$ref: '#/components/schemas/Summary'
LevelGeo:
type: object
required:
- id
- floor_number
- level_name
- lat
- lon
properties:
id:
$ref: '#/components/schemas/level_id'
floor_number:
$ref: '#/components/schemas/floor_number'
level_name:
$ref: '#/components/schemas/level_name'
lat:
$ref: '#/components/schemas/lat'
lon:
$ref: '#/components/schemas/lon'
LevelAvailability:
type: object
required:
- position
- occupied
properties:
position:
$ref: '#/components/schemas/PlaceShort'
occupied:
$ref: '#/components/schemas/occupied'
Level:
type: object
required:
- level_id
- floor_number
- level_name
properties:
level_id:
$ref: '#/components/schemas/level_id'
floor_number:
$ref: '#/components/schemas/floor_number'
level_name:
$ref: '#/components/schemas/level_name'
PlaceShort:
type: object
required:
- id
- lat
- lon
- group_id
properties:
id:
$ref: '#/components/schemas/position_id'
lat:
$ref: '#/components/schemas/lat'
lon:
$ref: '#/components/schemas/lon'
group_id:
$ref: '#/components/schemas/group_id'
LevelShortInfo:
type: object
required:
- group
- summary
properties:
level:
$ref: '#/components/schemas/LevelGeo'
summary:
$ref: '#/components/schemas/Summary'
Summary:
type: object
required:
- total
- occupied
- available
- undefined
properties:
total:
$ref: '#/components/schemas/counter'
occupied:
$ref: '#/components/schemas/counter'
available:
$ref: '#/components/schemas/counter'
undefined:
$ref: '#/components/schemas/counter'
PositionsAvailability:
type: object
required:
- positions_availability
- summary
properties:
positions_availability:
type: array
items:
$ref: '#/components/schemas/Availability'
summary:
$ref: '#/components/schemas/Summary'
Availability:
type: object
required:
- position
- occupied
properties:
position:
$ref: '#/components/schemas/Position'
occupied:
$ref: '#/components/schemas/occupied'
Position:
type: object
required:
- id
- lat
- lon
- group_id
- group_inner_id
- custom_id
- level
- network_id
properties:
id:
$ref: '#/components/schemas/position_id'
lat:
$ref: '#/components/schemas/lat'
lon:
$ref: '#/components/schemas/lon'
group_id:
$ref: '#/components/schemas/group_id'
level_id:
$ref: '#/components/schemas/level_id'
floor_number:
$ref: '#/components/schemas/floor_number'
GroupInfo:
type: object
required:
- id
- lat
- lon
properties:
id:
$ref: '#/components/schemas/group_id'
lat:
$ref: '#/components/schemas/lat'
lon:
$ref: '#/components/schemas/lon'
level_id:
$ref: '#/components/schemas/level_id'
floor_number:
$ref: '#/components/schemas/floor_number'
level_name:
$ref: '#/components/schemas/level_name'
ShortInfo:
type: object
required:
- group
- summary
properties:
group:
$ref: '#/components/schemas/GroupInfo'
summary:
$ref: '#/components/schemas/Summary'
Empty:
type: object
title: Empty Schema
parameters:
limit:
name: limit
in: query
description: "**Limits** the number of returned results"
schema:
type: integer
minimum: 0
multipleOf: 100
format: int32
limit50:
name: limit
in: query
description: "**Limits** the number of returned results"
schema:
type: integer
minimum: 0
default: 50
multipleOf: 100
format: int32
offset:
name: offset
in: query
description: "**Offset** from which start returned results"
schema:
type: integer
minimum: 0
default: 0
multipleOf: 100
format: int32
radius:
name: radius
in: query
description: "**Radius in Meters**. Distance from location based on `lat`/`lon`"
required: false
schema:
type: integer
minimum: 0
format: int32
lat:
name: lat
in: query
description: "**Latitude**. *Example: -0.39*. The latitude coordinate. Must be used with `lon`"
schema:
type: number
format: float
lon:
name: lon
in: query
description: "**Longitude**. *Example: 52.456*. Longitude coordinate. Must be used with `lat`"
schema:
type: number
format: float
zone_id:
name: zone_id
in: query
description: "**Zones**. *Example: [1,2,100]*. Array of zones ids"
required: false
schema:
type: array
items:
$ref: '#/components/schemas/zone_id'
owner_id:
name: owner_id
in: query
description: "**Owner**. *Example: 2*. **Only `admins` can use this param!** Field for filter data by owner."
required: false
schema:
$ref: '#/components/schemas/owner_id'
project_id:
name: project_id
in: query
description: "**Project**. *Example: [1,2,155]*. Field for filter data by project."
required: false
schema:
type: array
items:
$ref: '#/components/schemas/project_id'
position_id:
name: position_id
in: query
description: "**Positions**. *Example: [1,443,54]*. Array of positions ids"
required: false
schema:
type: array
items:
$ref: '#/components/schemas/position_id'
group_id:
name: group_id
in: query
description: "**Groups**. *Example: [1,443,54]*. Array of groups ids"
required: false
schema:
type: array
items:
$ref: '#/components/schemas/group_id'
device_id:
name: device_id
in: query
description: "**Devices**. *Example: [34FE1, AEB1]*. Array of devices ids"
required: false
schema:
type: array
items:
$ref: '#/components/schemas/device_id'
group_inner_id:
name: group_inner_id
in: query
description: "**Group inner ids**. *Example: [1, 10, 67]*. Array of group_inner_id"
required: false
schema:
type: array
items:
type: integer
format: int32
level:
name: level
in: query
description: "**Levels of positions**. *Example: [0, 1]*. Array of levels"
required: false
schema:
type: array
items:
type: integer
format: int32
level_id:
name: level_id
in: query
description: "**Levels of groups**. *Example: [0, 1]*. Array of levels"
required: false
schema:
type: array
items:
type: integer
format: int32
floor_number:
name: floor_number
in: query
description: "**Floor numbers of levels**. *Example: [0, 1]*. Array of floor numbers"
required: false
schema:
type: array
items:
type: integer
format: int32
active:
name: active
in: query
description: "**Devices active**. *Example: true*. Filter by devices active"
required: false
schema:
type: boolean
damaged:
name: damaged
in: query
description: "**Damaged Devices**. *Example: true*. Filter by damaged devices"
required: false
schema:
type: boolean
network_id:
name: network_id
in: query
description: "**Position network uuid. Can be array or string**. *Example: 23e4567-e89b-12d3-a456-426655440000, or: [00000000-0000-0000-0000-00007ffffffa, 123e4567-e89b-12d3-a456-426655440000]*. Filter by network_id"
required: false
schema:
type: array
items:
$ref: '#/components/schemas/network_id'
force:
name: force
in: query
description: "`Not a filter field!` If true the request will be return devices even if it doesn't have position - positions fields will be **null**"
required: false
schema:
type: boolean
bound:
name: bound
in: query
description: "**Bounded positions**. *Example: true*. Filter by bounded positions"
required: false
schema:
type: boolean
protocol:
name: protocol
in: query
description: "**Device protocol**. *Example: 2*. Filter devices by protocol."
required: false
schema:
type: integer
format: int32
firmware_id:
name: firmware_id
in: query
description: "**Device firmware_id**. *Example: 1*. Filter devices by firmware_id."
required: false
schema:
type: integer
format: int32
keys:
name: keys
in: query
description: "`Not a filter field!` If true, device object will include **encryption_keys** field as json"
required: false
schema:
type: boolean
time_from:
name: time_from
in: query
description: |
**UTC Timestamp with timezone**
Records with status_time greater than ```time_from``` will be returned.
required: false
schema:
type: string
format: date-time
time_to:
name: time_to
in: query
description: |
**UTC Timestamp with timezone**
Records with status_time less than ```time_to``` will be returned.
required: false
schema:
type: string
format: date-time
state:
name: state
description: "filters by occupation status"
in: query
required: false
schema:
type: string
enum: ['Occupied', 'Free']
example: 'Free'
responses:
not_found:
description: Requested resource not found, please check query parameters
unauthorised:
description: Unauthorized
|