Vertical Location API

The Vertical Location API provides two primary functions: determining the physical level of a building based on Wi-Fi scans (GET) and marking tasks as completed based on a matched location pattern (PUT).

Base URL

All requests to the Vertical Location API should be made to the following endpoint:

https://paas.v3nity.com/resource/track/data/verticallocation

Authentication

This API requires a valid Bearer Token. The token must be passed in the Authorization header.

Header Value Description
Authorization Bearer <ACCESS_TOKEN> Mandatory. The access token obtained during login.

GET Vertical Lookup

Determines the physical level or floor by analyzing nearby Wi-Fi hotspots.

Query Parameters

Parameter Type Description
s String Mandatory. A comma-separated list of SSIDs detected during the scan. Max length: 500 characters.
q String Mandatory. A comma-separated list of signal quality values corresponding to the SSIDs in the s parameter. Max length: 500 characters.
💡

Processing Limit

The server will process up to the first 15 hotspots provided in the request.

Request Example (GET)

https://paas.v3nity.com/resource/track/data/verticallocation?s=98:03:8e:75:44:90,b0:a7:b9:f6:a0:ea&q=-73,-79

JSON Response Schema (GET)

Field Type Description
pattern Integer The internal pattern ID matched for this location.
ssid String The SSID of the hotspot.
quality Integer The signal quality/strength.
address String The physical address associated with the pattern.
site String The site or sector name.
building String The building or route name.
level String The specific floor or level.
area String The area name.
postal String The postal code.
longitude Double The longitudinal coordinate.
latitude Double The latitudinal coordinate.

PUT Task Completion

Updates the completion status of a task by specifying a matched hotspot pattern and a timestamp.

Request Body Schema

Field Type Description
pattern Integer Mandatory. The hotspot pattern ID obtained from a previous GET request.
timestamp String Mandatory. The completion timestamp in ISO-8601 format (e.g., 2023-10-27T10:00:00+08:00).

Request Example (PUT)

{
  "pattern": 1024,
  "timestamp": "2023-10-27T10:00:00+08:00"
}

General Specifications

Request Headers

Header Value Description
Accept application/json Recommended for all requests.
Content-Type application/json Mandatory for PUT. Required when sending a JSON payload.

Status Codes

Code Description
200 OK Request processed successfully.
400 Bad Request GET: SSID and quality list does not tally.
PUT: No matching task found or task has already been completed.
401 Unauthorized Invalid or expired access token.
500 Internal Server Error An unexpected error occurred on the server.