Space API Reference v2
All resources represent physical or conceptual elements in form of GeoJSON compliant Features, with the following restrictions and additional foreign members per Sec. 6.1:
- A Resource object must contain the GeoJSON
idmember with a UUID value. - A Resource object must contain a
resourceTypemember with a Resource type value.
Floor resource
The Floor object
{
type: 'Feature',
resourceType: 'Floor',
id: '1ca271b9-7975-4a2c-8b62-ca118d374295',
properties: {
archived: false, // whether the floor is archived or not
area: 500, // Area in square meters
name: "5th floor", // name of the floor
elevation: 2.1, // meters vertically measured from point 0
northDirection: [1, 0], // 2D vector pointing north
private: false, // whether the floor is private or not
createdAt: "2021-07-09T12:32:23.533Z", // when the floor was created
floorNumber: "5", // optional property, description of the floor level (string field, not neccessary parsable to number)
labels: [ // user-defined labels attached to the floor
{
"color": "#ffab00",
"title": "Corporate"
}
]
},
resourceRelations: {
// is empty for archived floors
spaces: [
'dea1e7e5-2b1a-4f92-a4d5-5a18e9e31d9f',
'5ecee0b6-743f-4731-b294-d841a44814d1'
],
// is empty for archived floors
assets: [
'3d245ec4-0e33-4310-8f3d-143b5d1ec23c',
'24413ed3-de99-4402-a879-2d5e93bc53eb',
'6ff729e9-9111-49ec-8330-b2341151a5af'
]
},
geometry: {
// Describes the contour / outer shape of a Floor in WGS 84 coordinates
type: 'Polygon',
coordinates: [[
[-73.9895336425684, 40.7412823023507], [-73.98954794033, 40.7412868179835],
[-73.9895528256612, 40.7412860863857], [-73.9895576054433, 40.7412848084612],
[-73.9895680749846, 40.7412799280722], [-73.9895716707574, 40.7412768548214],
[-73.9895745785771, 40.7412737107194], [-73.9895767813852, 40.7412708641736],
[-73.9895765794105, 40.7412707741342], [-73.9898452450994, 40.7409021075081],
[-73.98985039, 40.7408922323802], [-73.989849947639, 40.7408845905923],
[-73.9898500511928, 40.7408845738501], [-73.9898487441441, 40.7408798965972],
[-73.9898446124742, 40.7408750048212], [-73.9896178136094, 40.7407794398655],
[-73.9896067770011, 40.7407767525407], [-73.9895991672847, 40.7407788124714],
[-73.9895901209793, 40.7407836048703], [-73.9895887271039, 40.7407881332852],
[-73.9895884512781, 40.7407927081052], [-73.9895233799189, 40.7412615614218],
[-73.9895234999116, 40.7412666948974], [-73.9895239115663, 40.7412697307808],
[-73.9895283424893, 40.7412787837426], [-73.9895336425684, 40.7412823023507]
]]
}
}
Get a single Floor
GET
v2/floor/{floorId}
Archived floors won't list resourceRelations.
Optional params
| param | type | default | description |
|---|---|---|---|
| includeCustomFields | boolean | false | Whether to include custom fields on the resource in the result |
Response
{
// Floor object without `geometry` property
}
Get a single Floor with GeoJSON
GET
v2/floor/{floorId}/geo-json
Optional params
| param | type | default | description |
|---|---|---|---|
| includeCustomFields | boolean | false | Whether to include custom fields on the resource in the result |
Response
{
// Floor object with `geometry` property
}
Query Floors
GET
v2/floor
List Floor objects matching at least one of the optional query parameters.
To list both private and public resources, both of the floor:queryPublic and floor:queryPrivate scopes must be provided in the access token. If just one of the scopes is provided, then the query only returns resources that fall into that category. For example, a query with an access token that only has floor:queryPublic scope will only return public floors of the team.
Optional params
| param | type | default | description |
|---|---|---|---|
| name | string | null | List all Floors with a specific name with wildcard support |
| spaceId | uuid | null | List Floors including a specific space |
| assetId | uuid | null | List Floors including a specific asset |
| geometry | boolean | false | Whether to include geometry property of the floors in the results |
| includeCustomFields | boolean | false | Whether to include custom fields on the resource in the result |
| includeArchived | boolean | false | Whether to include archived floors in the result |
| label | string | null | Filter for Floors with the specified label |
| limit | int | 200 | Pagination support for large results, max 200 |
| offset | int | 0 | Pagination support for large results |
Response
The response will include a maximum of 200 Floor items per page.
{
type: 'FeatureCollection',
features: [
// Floor object(s)
]
}
Floorplan as raster or vector image
POST
v2/floor/{floorId}/2d-image
It is possible to fetch the floorplan as png or svg image with a high level of customization.
With a JSON body using default formatting:
{
format: 'svg' // svg | png
}
Or with customizations:
{
format: 'svg', // svg | png
fpeOptions: {
hideElements: {},
theme: {},
planRotation: 90,
units: {}
}
}
Where fpeOptions is of type StartupOptions as defined in the Floor Plan Engine API reference.
Response:
{
"imageUrl": "https://testing-storage.3d.io/fpe/floor/0c27993f-4e3d-4eae-96fd-ef01bc1cc878-e507948193a7ea036ec0b313bee0b67a.svg",
"latLngBounds": [
[8.519898816608844, 47.37704318568811],
[8.520652662643258, 47.37733122877267]
]
}
Where imageUrl is permanent link to the image, latLngBounds specify the top-left and bottom-right corners of the image.
Scene Structure
GET
v2/floor/{floorId}/scene-structure
Read the Archilogic scene structure of the floor.
Optional params
| param | type | default | description |
|---|---|---|---|
| includeMetadata | boolean | false | Whether to include scene structure metadata in the result |
Response
{
structure: // Archilogic scene structure
metadata: // Scene structure metadata
}
Get DXF
GET
v2/floor/{floorId}/dxf
Returns a DXF file URL generated from the floor's scene structure, valid for 60 minutes.
Response
{
downloadUrl: // URL to download DXF
}
Archive Floors
POST
v2/floor/{floorId}/archive
Archive Floors by floor id. Spaces and assets can not be queried for archived floors.
Response
{
message: 'Successfully archived scene <sceneId>.'
}
Unarchive Floors
POST
v2/floor/{floorId}/unarchive
Unarchive Floors by floor id
Response
{
message: 'Successfully unarchived scene <sceneId>.'
}
Space resource
The Space object
Take a look at the space taxonomy for reference
{
type: 'Feature',
resourceType: 'Space',
id: '0804efc7-6dcd-416b-b439-a6d8191200ae',
properties: {
area: 57, // Area in square meters
center: [],// center defined as most distant point from the contour
usage: "meetingRoom", // Human readable description of space usage
program: "meet", // space program that the usage belongs to
height: 2.8, // height in meters
northDirection: [1, 0], // 2D vector pointing north
customId: '101A', // custom ID string
name: 'Meeting Room Type A' // space name string
},
resourceRelations: {
floors: [
'dea1e7e5-2b1a-4f92-a4d5-5a18e9e31d9f'
],
assets: [
'3d245ec4-0e33-4310-8f3d-143b5d1ec23c',
'24413ed3-de99-4402-a879-2d5e93bc53eb'
]
},
geometry: {
// Describes the inner shape of a space in WGS 84 coordinates
type: 'Polygon',
coordinates: [[
[-73.9896565570417, 40.7411498833846], [-73.9896104593945, 40.7411304475015],
[-73.9895926916832, 40.7411548285941], [-73.9895977867848, 40.7411680018768],
[-73.989632638668, 40.7411827044963], [-73.9896565570417, 40.7411498833846]
]]
},
geometryOpenings: [
// Openings along the boundary polygon
{
type: "door",
edgeIdx: [0,2], // maps hierarchically to one item in geometry.coordinates
pos: 0.2, // position along the polygon edge [meters]
y: 0, l: 0.8, h: 2.1, // Y position, length, height [meters]
id: '7a86dd86-f8ee-403a-aafa-fef3c2ed15e8' // enables matching of openings across spaces
},
{ type: "window", edgeIdx: [0,4], pos: 1, y: 0.6, l: 1.6, h: 1.6, id: '...' }
{ type: "window", edgeIdx: [1,1], pos: 0.3, y: 0.6, l: 1.6, h: 1.6, id: '...' }
]
}
Get a single Space
GET
v2/space/{spaceId}
Spaces in archived floors can not be queried.
Optional params
| param | type | default | description |
|---|---|---|---|
| includeCustomFields | boolean | false | Whether to include custom fields on the resource in the result |
Response
{
// Space object without `geometry` and `geometryOpenings` properties.
}
Get a single Space with GeoJSON
GET
v2/space/{spaceId}/geo-json
Optional params
| param | type | default | description |
|---|---|---|---|
| includeCustomFields | boolean | false | Whether to include custom fields on the resource in the result |
Response
{
// Space object with `geometry` and `geometryOpenings` properties.
}
Query Spaces
GET
v2/space
List space objects matching at least one of the optional query parameters.
To list both private and public resources, both of the floor:queryPublic and floor:queryPrivate scopes must be provided in the access token. If just one of the scopes is provided, then the query only returns resources that fall into that category. For example, a query with an access token that only has floor:queryPublic scope will only return spaces from public floors of the team.
Optional params
| param | type | default | description |
|---|---|---|---|
| floorId | uuid | null | List all spaces within a Floor |
| assetId | uuid | null | List spaces including in a specific asset |
| geometry | boolean | false | Whether to include geometry and geometryOpenings properties of the spaces in the results |
| includeCustomFields | boolean | false | Whether to include custom fields on the resource in the result |
| limit | int | 500 | Pagination support for large results, max 500 |
| offset | int | 0 | Pagination support for large results |
Response
The response will include a maximum of 500 space items per page.
{
type: 'FeatureCollection',
properties: {
offset: 200,
warnings: []
},
features: [
// space object(s)
]
}
Asset resource
The Asset object
Take a look at the product taxonomy for reference
{
type: 'Feature',
resourceType: 'Asset',
id: '5c94ac2b-06eb-4aa7-b443-cf24b19c4a07', // unique identifier of the furniture element
properties: {
dimensions: {}, // 3D bounding box dimensions
categories: ['seating'], // product category
subCategories: ['taskChair'], // product subCategory
manufacturer: '', // Manufacturer brand name or company name
name: '', // string Name of the product
productId: '35fa5b72-b2c2-47bc-ae65-5ea4abf6b17b', // string unique identifier of the product
tags: [], //
seatCapacity: 2, // number of people who can be seated on asset (only set for categories seating, softSeating, and booth)
northDirection: [1, 0] // 2D vector pointing north
},
resourceRelations: {
floors: [
'dea1e7e5-2b1a-4f92-a4d5-5a18e9e31d9f'
],
spaces: [
'3d245ec4-0e33-4310-8f3d-143b5d1ec23c'
]
},
geometry: {
// Describes the outer shape of an asset in WGS 84 coordinates
type: 'Polygon',
coordinates: [[
[-73.9896290125206, 40.7411811304675], [-73.9896313084026, 40.7411779800182],
[-73.989614740846, 40.7411709947361], [-73.989612444964, 40.7411741451855],
[-73.9896290125206, 40.7411811304675]
]]
}
}
Get a single Asset
GET
v2/asset/{assetId}
Assets in archived floors can not be queried.
Optional params
| param | type | default | description |
|---|---|---|---|
| includeCustomFields | boolean | false | Whether to include custom fields on the resource in the result |
Response
{
// Asset object without `geometry` property
}
Get a single Asset with GeoJSON
GET
v2/asset/{assetId}/geo-json
Optional params
| param | type | default | description |
|---|---|---|---|
| includeCustomFields | boolean | false | Whether to include custom fields on the resource in the result |
Response
{
// Asset object with `geometry` property
}
Query Assets
GET
v2/asset
List assets objects matching at least one of the optional query parameters.
To list both private and public resources, both of the floor:queryPublic and floor:queryPrivate scopes must be provided in the access token. If just one of the scopes is provided, then the query only returns resources that fall into that category. For example, a query with an access token that only has floor:queryPublic scope will only return assets from public floors of the team.
Optional params
| param | type | default | description |
|---|---|---|---|
| floorId | uuid | null | List all assets within a Floor |
| spaceId | uuid | null | List all assets within a space |
| geometry | boolean | false | Whether to include geometry property of the assets in the results |
| includeCustomFields | boolean | false | Whether to include custom fields on the resource in the result |
| limit | int | 1000 | Pagination support for large results, max 1000 |
| offset | int | 0 | Pagination support for large results |
Response
The response will include a maximum of 1000 asset items per page.
{
type: 'FeatureCollection',
properties: {
offset: 5000,
warnings: []
},
features: [
// asset object(s)
]
}
Custom Fields
Floor, Space and Asset resources can have Custom fields attached, containing user defined data in JSON format.
Get a single Custom Field
GET
v2/{resourceType}/{resourceId}/custom-field/{jsonKeyPath}
Example:
GET v2/space/1234-5678-9012/custom-field/properties.customFields.myRoomInfo.confSystemDetails
Responds with HTTP status 200 and body:
{
"hasScreen": "true",
"compatible": ["zoom", "google", "tel"],
"hasDeskMic": true
}
Or with HTTP status 404 if the custom field has not been set for a specific resource.
Get all Custom Fields for a Resource
GET
v2/{resourceType}/{resourceId}/custom-field
Returns all custom fields attached to a specific resource.
Exemplary Response
{
"properties": {
"customFields": {
"myRoomInfo": {
"confSystemDetails": {
"hasScreen": true,
"compatible": ["zoom", "google", "tel"],
"hasDeskMic": true
}
},
"booking": {
"isOccupied": true,
"meetingParticipants": ["Bruce Wayne", "Clark Kent"]
}
}
}
}
Set Custom Fields
Add or update a custom fields attached to another resource, specified by resourceId at a .
Recommendation: Use URL safe field names.
PUT
v2/{resourceType}/{resourceId}/custom-field/{jsonKeyPath}
Example:
Sending a PUT request to URL:
PUT v2/space/1234-5678-9012/custom-field/properties.customFields.myRoomInfo.confSystemDetails
with a JSON body:
{
hasScreen: true,
compatible: ["zoon', "google", "tel"],
hasDeskMic: true
}
will set the custom field property and respond with:
200 OK with body: {}
Delete Custom Fields
DELETE
v2/{resourceType}/{resourceId}/custom-field/{jsonKeyPath}
Example:
DELETE v2/space/1234-5678-9012/custom-field/properties.customFields.myRoomInfo.confSystemDetails.hasScreen
Response
200 OK with body: {}