Spaces Platform

The Spaces Platform gives developers programmatic access to Zapworks Spaces, our app-free indoor navigation tool. Use it to keep a Space in step with your own systems, automate how Spaces are set up, or build your own wayfinding experiences on the same data and routing that power Spaces.

What is Spaces?

Spaces turns a 3D scan of a building into turn-by-turn indoor navigation that runs for visitors without any app installation. A visual positioning system (VPS) works out where visitors are from their phone’s camera, with no beacons or other hardware to install. Visitors start by scanning a QR code or opening a link, and they’re guided to where they want to go, across as many floors as the building has.

Spaces can be set up and managed entirely in the Spaces web app, an easy to use (no-code) editor. See the Spaces documentation for how it works and how to create your first Space.

What you can build

The platform opens up everything you can do in the web app, and more. For example, you can:

• Keep landmarks up to date automatically, for example by syncing meeting rooms, shops or desks from a booking system or CMS.
• Build your own navigation experience, using Spaces’ routing in your own app, website or kiosk.
• Plan routes on demand between any two points or landmarks, with options for step-free routes and avoiding elevators.
• Help visitors find the right Space by searching for public Spaces near their location.
• Bring in data you already have, or take it elsewhere, using the IMDF indoor mapping standard.
• Set Spaces up at scale, scripting the setup and updates you’d otherwise make by hand.

How a Space is organised

Whether you’re using the API or the client, you’ll be working with these parts of a Space:

Space	The building or area being navigated, with its name, address, settings and location in the world.
Entities	Everything placed in the Space. Each has a type: landmarks (the destinations visitors can navigate to), doors, obstacles, navigation aids and more.
Floors	The levels of the Space. Floors are worked out from the scan each time the navigation mesh is generated.
Tags	Categories that landmarks are listed under, so visitors can search for places by category.
Navigation mesh	The walkable area that routes are planned across. It’s generated from the scan, and regenerated when the Space’s structure changes.

Positions in a Space are [x, y, z] coordinates in metres, with y pointing up.

Live and published data

Changes made through the API are merged in real time with changes from other API requests and from people editing the Space in the web app.

Visitors don’t see the live data directly. They see the version of the Space that was last published, which is updated within 15 seconds of a change and may be cached for up to 15 seconds more. So changes can take up to about 30 seconds to reach visitors.

The REST API

The Spaces REST API is the foundation of the platform. It works from any language that can make HTTP requests, and lets you:

• create, update and remove landmarks and other entities, floors and tags
• plan routes between positions or landmarks, with step-free and elevator options, and get back the distance, steps, elevators used and waypoints
• import and export data, including as IMDF GeoJSON
• find public Spaces near a location
• manage files, settings, public access and saved versions (commits) of a Space
• regenerate the navigation mesh

Authenticate with a Zapworks API key or user token. If your organization uses OIDC, you can exchange OIDC tokens for short-lived tokens for use with the API. Public Spaces can be read, and routes planned through them, without any token. The REST API reference covers authentication and every operation in detail.

The API endpoint for a Space can vary depending on where its data is stored, and use of the API is subject to rate limits. Get in touch and we’ll give you the right endpoint and arrange limits that suit what you’re building.

The TypeScript API client

If you’re working in TypeScript or JavaScript, the Spaces API client is the quickest way to use the API. It runs in the browser, Node.js and edge runtimes, and it:

• handles authentication, including refreshing tokens and exchanging OIDC tokens from your identity provider
• retries automatically when you hit a rate limit
• turns API errors into exceptions you can catch
• includes types for every part of a Space, so your editor can autocomplete fields and catch mistakes

import { SpacesClient } from '@zwspaces/api-client';

const client = new SpacesClient({
  endpoint: 'https://<your-api-endpoint>',
  token: process.env.ZAPWORKS_API_KEY,
});

const space = client.space('<your-space-id>');
const landmarks = (await space.entities.list()).filter((e) => e.type === 'landmark');

See Getting Started with the TypeScript API Client to set it up.

Getting started

1. Create a Space in Zapworks, following the Spaces getting started guide, if you don’t have one already.
2. Get your API endpoint and access. Contact us for your Space’s API endpoint. Then create a Zapworks API key, or ask us to set up OIDC with your identity provider so your users can sign in with their own accounts.
3. Make your first request, with the TypeScript API client or directly with the REST API.

Security and compliance

Zapworks is ISO 27001-certified. Spaces supports SSO-enabled access controls, including signing in to the API through your own identity provider with OIDC, and flexible self-hosting options for deployments that need full control over data and infrastructure. Independent and self-hosted deployments of Spaces have more ways to authenticate with the API. Get in touch to find out more.