Unit Map® REST API (v1.20230606)

Download OpenAPI specification:Download

Introduction

The Unit Map® REST API uses standard HTTP verbs to communicate and HTTP status codes to indicate status and errors. All responses come in standard JSON. The API is served over HTTPS to ensure data privacy; HTTP is not supported.

Versioning

Versions are communicated as VERSION.RELEASE-DATE, where VERSION denotes the version number of the API and prefixed to all API request paths, such as /v1/maps. RELEASE-DATE denotes backwards-compatible changes to the API.

When any non-backwards compatible additions must be made to the API, the version number will be incremented.

Backwards-compatible changes

We consider the following changes to be backwards-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of object IDs or other opaque strings.
  • You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If for example you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).

Authentication

For requests which require Authentication, an API Key can be provided by either the api-key query parameter or API-Key header. We recommend the header over the query parameter as it avoids your API key from being stored in browser history and most server logs. If neither query parameter or header is provided, a 401 status code is returned with the following JSON:

{
  "message": "No API key found in request"
}

If your API key cannot be validated, a 403 status code is returned with the following JSON:

{
  "message": "Invalid authentication credentials"
}

API Key

An API key sent via the API-Key header.

curl -i -H "API-Key: 12345" https://api.unitmap.com/v1/maps
Security Scheme Type: API Key
Header parameter name: API-Key

Experimental features

We provide new API features via experimental flags. This allows users to opt-in for new functionality and provide feedback prior to a feature becoming generally available (GA). We believe in stability without stagnation. This ability allows our team to build and ship best-in-class APIs faster while upholding backwards-compatibility on GA features.

Experimental features are subject to change while undergoing development and feedback. Therefore, they are exempt from any backwards-compatibility guarantees until they reach GA. We do not expect nor recommend using experimental features in production environments unless a partnership has been established with our teams working closely together.

Flags are provided via the Experimental-Flags header. A comma-separated list is expected in order to pass multiple flags on a single request.

curl -i https://api.unitmap.com/v1/assets \
  -H "API-Key: 12345" \
  -H "Experimental-Flags: flag-1,flag-2"

Errors

The Unit Map API uses standard HTTP status codes to indicate the success or failure of the API request. The body of the response will be JSON in the following format:

{
  "message": "Not found"
}

Assets

List assets

Returns a list of assets.

Authorizations:
API Key
query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    • "per_page": 1000,
    • "current_page": 1,
    • "prev_url": null,
    • "next_url": null
    },
  • "data": [
    • {
      }
    ]
}

View an asset

Returns a specific asset.

Authorizations:
API Key
path Parameters
asset
required
string <id> <= 255 characters

An asset ID.

Responses

Response samples

Content type
application/json
{
  • "id": "1323",
  • "market": "multifamily",
  • "name": "The Lofts at New Main",
  • "created_at": "2017-09-11T17:08:59+00:00",
  • "updated_at": "2019-10-10T04:25:58+00:00"
}

Floors

List floors

Returns a list of floors for an asset.

Authorizations:
API Key
path Parameters
asset
required
string <id> <= 255 characters

An asset ID.

query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    • "per_page": 1000,
    • "current_page": 1,
    • "prev_url": null,
    • "next_url": null
    },
  • "data": [
    • {
      }
    ]
}

View a floor

Returns a specific floor for an asset.

Authorizations:
API Key
path Parameters
asset
required
string <id> <= 255 characters

An asset ID.

floor
required
string <id> <= 255 characters

A floor ID.

Responses

Response samples

Content type
application/json
{
  • "id": "4730",
  • "asset_id": "1323",
  • "name": "1",
  • "label": "Floor 1",
  • "short_label": "1",
  • "sort": 2,
  • "created_at": "2017-09-11T17:09:17+00:00",
  • "updated_at": "2019-01-02T22:01:09+00:00"
}

References

References provide asset ID mappings from Unit Map to other third-party systems.

List references

Returns a list of asset references.

Requires unitmap.asset-references.read permission.

NOTICE: This resource is experimental and requires the references experimental flag.

Authorizations:
API Key
query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

asset
string <id> <= 255 characters

An asset ID to filter the list on.

key
string <= 255 characters ^[a-z]{1}[a-z0-9-]{1,254}$

A key value to filter the list on.

header Parameters
Experimental-Flags
required
string

This resource is experimental and requires the references experimental flag.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    • "per_page": 1000,
    • "current_page": 1,
    • "prev_url": null,
    • "next_url": null
    },
  • "data": [
    • {
      }
    ]
}

Units

List units

Returns a list of units.

Authorizations:
API Key
query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    • "per_page": 1000,
    • "current_page": 1,
    • "prev_url": null,
    • "next_url": null
    },
  • "data": [
    • {
      }
    ]
}

View a unit

Returns a specific unit.

Authorizations:
API Key
path Parameters
unit
required
string <id> <= 255 characters

A unit ID.

Responses

Response samples

Content type
application/json
{
  • "id": "258670",
  • "asset_id": "1323",
  • "floor_id": "1",
  • "name": "E13",
  • "created_at": "2017-09-11T17:09:18+00:00",
  • "updated_at": "2018-01-20T03:44:39+00:00"
}

References

References provide unit ID mappings from Unit Map to other third-party systems.

List references

Returns a list of unit references.

Requires unitmap.unit-references.read permission.

NOTICE: This resource is experimental and requires the references experimental flag.

Authorizations:
API Key
query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

asset
string <id> <= 255 characters

An asset ID to filter the list on.

key
string <= 255 characters ^[a-z]{1}[a-z0-9-]{1,254}$

A key value to filter the list on.

header Parameters
Experimental-Flags
required
string

This resource is experimental and requires the references experimental flag.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    • "per_page": 1000,
    • "current_page": 1,
    • "prev_url": null,
    • "next_url": null
    },
  • "data": [
    • {
      }
    ]
}

Unit Maps

List unit maps

Returns a list of allowed unit maps.

Authorizations:
API Key
query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

tags
string <id> <= 255 characters

A comma-separated list of one or more tags to filter the list on (e.g. tag-1,tag-2).

asset
string <id> <= 255 characters

An asset ID to filter the list on.

Responses

Response samples

Content type
application/json
{}

Parse unit map SVG data

Requires unitmap.unit-maps.parse permission

Authorizations:
API Key
Request Body schema: application/vnd.umap+xml
required
string

Responses

Response samples

Content type
application/vnd.umap+json
{
  • "version": "1.2",
  • "type": "application/vnd.umap+json",
  • "width": 2000,
  • "height": 2000,
  • "elements": [
    • {
      }
    ]
}

View a unit map

Returns a specific unit map.

Authorizations:
API Key
path Parameters
map
required
string <id> <= 255 characters

A unit map ID.

Responses

Response samples

Content type
application/json
{}

Backgrounds

List backgrounds

Returns a list of backgrounds for a unit map.

Authorizations:
API Key
path Parameters
map
required
string <id> <= 255 characters

A unit map ID.

query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

Responses

Response samples

Content type
application/json
{}

View a background

Returns a specific background for a unit map.

Authorizations:
API Key
path Parameters
map
required
string <id> <= 255 characters

A unit map ID.

background
required
string <id> <= 255 characters

A background ID.

Responses

Response samples

Content type
application/json
{}

Level Tags

List level tags

Returns a list of all level tags for a unit map.

Authorizations:
API Key
path Parameters
map
required
string <id> <= 255 characters

A unit map ID.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ]
}

Units

List units

Returns a list of units for a unit map.

Authorizations:
API Key
path Parameters
map
required
string <id> <= 255 characters

A unit map ID.

query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    • "per_page": 1000,
    • "current_page": 1,
    • "prev_url": null,
    • "next_url": null
    },
  • "data": [
    • {
      }
    ]
}

View a unit

Returns a specific unit for a unit map.

Authorizations:
API Key
path Parameters
map
required
string <id> <= 255 characters

A unit map ID.

unit
required
string <id> <= 255 characters

A unit ID.

Responses

Response samples

Content type
application/json
{
  • "id": "258670",
  • "asset_id": "1323",
  • "floor_id": "1",
  • "name": "E13",
  • "created_at": "2017-09-11T17:09:18+00:00",
  • "updated_at": "2018-01-20T03:44:39+00:00"
}