Noccela developer hub
Build on Noccela location data with OAuth 2.0 client credentials, a real-time WebSocket stream, an HTTP API described in OpenAPI, Push API webhooks and an SDK.
Every position, zone event and tag state in a Noccela system is available to your own software. You authenticate once with OAuth 2.0, then choose how the data reaches you: ask for it over HTTP, stream it over a WebSocket, or let Noccela push events to your endpoint.
What you can build
Live maps and dashboards
Draw tags on your own floor plans and dashboards, updated as positions are computed.
WMS, MES and ERP integrations
Turn zone entries, dwell times and button presses into transactions in your business systems.
Safety and alert applications
React to zone events, make a tag buzz or a Signalling Flash light up, and confirm calls for assistance.
Analytics and BI
Pull position history for utilisation, flow and spaghetti diagrams, or stream it into your data platform.
Sports analytics
Feed player and animal positions into performance software at high update rates.
Installation tools
Read and edit site layouts, suggest base station positions and run automatic calibration from your own tooling.
Architecture
Your application gets an access token from the Noccela authorisation server with its client ID and secret, then uses the token with any of the three APIs.
Your application
A backend service or integration that holds a client ID and secret
OAuth 2.0 client credentials
auth.noccela.io/connect/token
Returns a JWT access token, valid for a limited time
The token opens all three APIs
- HTTP API https://api.noccela.io Request and response: sites, layouts, devices, history, installation tools, workflows and Push API administration.
- Real-time API wss://{node}/realtime A WebSocket stream from the positioning engine: live positions, tag state changes, alerts and layout changes.
- Push API Your HTTPS endpoint Noccela calls your endpoint when a tag enters or leaves an area, or when a tag or base station changes state.
Large initial payloads on the real-time API, such as the full state of every tag on a site, are encoded with MessagePack to save bandwidth; everything else is JSON. Real-time connections go to the server node that runs your site, which the HTTP API tells you.
The data you get
| Data | What it contains | Where |
|---|---|---|
| Positions | x, y, z in site coordinates, floor, timestamp, uncertainty radius | Real-time API; HTTP history |
| Tag state | Name, battery, online and sleep status, areas the tag is in, motion, model, firmware, button and sensor states | Real-time API; HTTP API; Push API |
| Zone events | Tag entered or left an area, time spent, nearest entrance point | Push API |
| Alerts | Alerts raised on the site and the path that led to them | Real-time API |
| Site layout | Floors, layers, blueprints, areas, walls, base station positions | Real-time API; HTTP API |
| Base stations | Online status, positions, radio and diagnostics | Real-time API; HTTP API; Push API |
| History | Stored positions and states, with a new row whenever a tag has moved more than 0.5 m | HTTP API |
Devices are identified by their device ID, the serial number printed on the label. See the data model for accounts, sites, floors, layers and coordinates.
Documentation
Getting started
- Quickstart: stream live tag positions Five steps from credentials to live data: get an OAuth 2.0 token, find your site's server, connect over WebSocket, stream tag positions and load the floor plan. Read
- Authentication Noccela APIs use OAuth 2.0 client credentials: create an app, request a JWT access token, send it as a Bearer header or WebSocket message, refresh it in time. Read
- Data model How Noccela data is organised: accounts and sites, layouts with floors, layers and items, devices and their IDs, tag state fields, and site coordinates. Read
API reference
- Real-time API (WebSocket) The Noccela real-time API streams positions, tag states, alerts and layout changes over WebSocket: connecting, authentication, message format, message types. Read
- HTTP API reference Every endpoint of the Noccela Partner API v1.3, grouped as in its OpenAPI description: devices, sites, layouts, history, Push API, installation and workflows. Read
- Push API (webhooks) The Noccela Push API sends HTTPS requests to your endpoint when tags enter or leave areas or change state. Set-up, validation, retries, event types, payloads. Read
Resources
- JavaScript SDK ncc-cloud-integration-js wraps the Noccela real-time API: install it from GitHub, connect an EventChannel, subscribe to positions and let it handle reconnects. Read
- Changelog Dated changes to the Noccela APIs, SDK and developer documentation, newest first, with the current API version and how breaking changes are announced. Read
- API terms (summary) A plain-language summary of the terms for using Noccela APIs and SDKs: credentials, acceptable use, data roles, versioning, availability, safety and liability. Read
Tools and resources
- Swagger UI Browse and try every HTTP endpoint.
- OpenAPI description Generate a client in your language.
- JavaScript SDK WebSocket client with reconnects and token refresh.
- API document (PDF) Full message schemas for API version 1.3.
Get access
The APIs serve Noccela customers and partners. To evaluate them before you have a site of your own, request sandbox credentials: a client ID and secret for a demo site.
Before you go live, read the API terms and check the changelog.