Space API Reference v1 [BETA]

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 compliant Features, with the following restrictions and additional foreign members per Sec. 6.1:

  • 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: {
    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
  },
  resourceRelations: {
    spaces: [
      'dea1e7e5-2b1a-4f92-a4d5-5a18e9e31d9f',
      '5ecee0b6-743f-4731-b294-d841a44814d1'
    ],
    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}

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
query (later) string null SQL type string for relational queries
buildingId (later) uuid null List all Floors within a building
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
organizationId uuid <your-org-id> List all Floors within an organization
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 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

Space resource

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

The Space object

{
  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: "executiveOffice", // Human readable description of space usage
    program: "work", // space program that the usage belongs to
    externalIds: [], // Array of user specified identifiers
    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}

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
query (later) string null SQL type string for relational queries
buildingId (later) uuid null List all spaces within a building
floorId uuid null List all spaces within a Floor
assetId uuid null List spaces including in a specific asset
organizationId uuid <your-org-id> List all spaces within an organization
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: {
    externalIds: [], // Array of user specified identifiers
    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}

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
query (later) string null SQL type string for relational queries
buildingId (later) uuid null List all assets within a building
floorId uuid null List all assets within a Floor
spaceId uuid null List all assets within a space
organizationId uuid <your-org-id> List all assets within an organization
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: {}