Skip to content

Get a entity

GET
/{resource}/data/entities/{id}
curl --request GET \
--url https://example.com/v1/example/data/entities/example \
--header 'Authorization: Bearer <token>'

With Accept: application/geo+json, returns IMDF features: landmarks as amenities, doors as openings, obstacles as fixtures and elevator call panels as elevator amenities. Other entities have no IMDF equivalent. IMDF positions are worked out from the space’s georeference, so these need one.

resource
required
string
/^\d+$/

The project ID of the space

id
required
string
>= 1 characters <= 256 characters

The entity’s id

The entity

One of: discriminator: type

A way through a wall that would otherwise divide the walkable area, such as a doorway. Routes can pass through it in either direction, between points 1m in front of and 1m behind its pose, which is placed on the wall facing out of it. Applied when routes are worked out, so it doesn’t need the navigation mesh to be regenerated.

object
id
required

Identifies the entity. Equal to its key in the space’s entities. Treat it as opaque - new ones are usually UUIDs.

string
>= 1 characters
hidden

Leaves a landmark out of what visitors are shown. It doesn’t stop any entity from affecting routes.

boolean
pose

Where the entity is, and which way it faces. Entities placed by their points don’t use it.

object
position
required

A point [x, y, z] in metres, in the space’s coordinate frame. The frame is shared by every floor and map, with +y up.

array
>= 3 items <= 3 items
quaternion
required

A rotation as a unit quaternion [x, y, z, w]. [0, 0, 0, 1] is no rotation.

array
>= 4 items <= 4 items
aqrs

Accessible QR codes linked to the entity. Currently only used for landmarks.

Array<object>

A physical Accessible QR code (AQR) placed in the space and linked to an entity. Visitors can scan it for more information when settings.scanForAQRs is on.

object
url
required

The URL encoded in the code, which identifies that individual code and the information it links to.

string
category

The code’s numeric category. It can be read from further away than the URL, so it’s used to match a code before its URL has been read.

number
imdf

How the entity relates to IMDF.

object
category

The IMDF category to export the entity with, in place of the one worked out from its type and category - e.g. atm.

string
imported

Whether the entity was created by an IMDF import.

boolean
type
required
string
Allowed value: door
roles

Reserved for limiting the door to certain roles. Not used yet.

object
key
additional properties
boolean

Example

{
"pose": {
"position": [
1.5,
0,
-3.2
],
"quaternion": [
0,
0,
0,
1
]
},
"type": "door"
}

The token is missing or invalid.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

The token has no access to this space.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

No item has this id.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

The item has no IMDF equivalent.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

An item with this id already exists or the space is being duplicated - or, for IMDF, the space has no georeference or floors (noGeoreference, noFloors) or is missing information IMDF requires (imdfIncomplete).

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

Too many requests. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}
Retry-After
integer

Seconds to wait before retrying

Something upstream failed.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

The space is moving between servers. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}
Retry-After
integer

Seconds to wait before retrying

Something upstream timed out.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}