Space API Reference v1

REST version uptime

https://docs.google.com/drawings/d/13CWNI2FiX-39UU_GK-CYPm0dnAtRDEo81s014ERkhu8/edit

All resources represent physical or conceptual elements in form of GeoJSON (opens new window) compliant Features (opens new window), with the following restrictions and additional foreign members per Sec. 6.1 (opens new window):

  • A Resource object must contain the GeoJSON id member with a UUID value.
  • A Resource object must contain a resourceType member with a Resource type value.

Floor resource

https://docs.google.com/drawings/d/1zJaBXR6IZcJyRmaKUvLN0XyCF39iUELbnNMOBNb6DRs/edit

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
    level: 5, // stacking order 0 = ground level
    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
  },
  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

v1/floor/{floorId}

Archived floors won't list resourceRelations

Response

{
  // Floor object
}

Query Floors

GET

v1/floor

List Floor objects matching at least one of the following params:

Optional params

param type default description
name uuid 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
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

v1/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 (opens new window) 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.

floorplan

Archive Floors

POST

v1/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

v1/floor/{floorId}/unarchive

Unarchive Floors by floor id

Response

{
  message: 'Successfully unarchived scene <sceneId>.'
}

Space resource

https://docs.google.com/drawings/d/1WE5pfuEb010pE-Q8R1t4ewo_CuJxtAj71VcEr91iRvk/edit

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
  },
  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

v1/space/{spaceId}

Spaces in archived floors can not be queried.

Response

{
  // space object
}

Query Spaces

GET

v1/space

List space objects matching at least one of the following params:

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
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

https://docs.google.com/drawings/d/1PrKiTuVvYiKMKYKppcistMoshzNRHvj6DlXlSIgm-Eo/edit

The Asset object

{
  type: 'Feature',
  resourceType: 'Asset',
  id: '5c94ac2b-06eb-4aa7-b443-cf24b19c4a07', //	unique identifier of the furniture element
  properties: {
    dimensions: {}, //	3D bounding box dimensions
    categories: [],	//
    manufacturer: '', // Manufacturer brand name or company name
    name: '', //	string	Name of the product
    productId: '', //	string	unique identifier of the product
    tags: [], //
    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

v1/asset/{assetId}

Assets in archived floors can not be queried.

Response

{
  // asset object
}

Query Assets

GET

v1/asset

List assets objects matching by at least one of the following params:

Optional params

param type default description
floorId uuid null List all assets within a Floor
spaceId uuid null List all assets within a space
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

v1/{resourceType}/{resourceId}/custom-field/{jsonKeyPath}

Example:

GET v1/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

v1/{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

v1/{resourceType}/{resourceId}/custom-field/{jsonKeyPath}

Example:

Sending a PUT request to URL:

PUT v1/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

v1/{resourceType}/{resourceId}/custom-field/{jsonKeyPath}

Example:

DELETE v1/space/1234-5678-9012/custom-field/properties.customFields.myRoomInfo.confSystemDetails.hasScreen

Response

200 OK with body: {}