Version: 2.0

Maps

Introduction

Maps allow users to visualize their access control system by assigning coordinates to devices. There are two types of maps:

Local maps are based on user-provided images, with coordinates provided as pixel values relative to the top left corner of each image. A system may contain multiple local maps.
Global maps are based on third-party mapping services (like Google Maps), with coordinates provided as geographical latitude and longitude values. A system may only contain one global map.

Note that pdk.io currently only supports local maps, but global maps may be utilized by third-party applications.

The map object

Local
Global

{
  "id": "0b4078ac-f150-46d2-b320-b0a0544f8bfd",
  "name": "Test Map 1",
  "description": "Test Map 1",
  "partitions": ["619cceb0-ac58-4b15-a8ec-32efcb0476ba"],
  "type": "local",
  "imageUrl": "http://systems.pdk.io/images/22ba2c70-631a-11ee-90fc-598e4a89e620",
  "opacity": 100,
  "iconSize": "M",
  "devices": [
    {
      "id": "f90bef5c-1a2b-4763-9fc4-f059c6fd55ba",
      "displayName": true,
      "x": 100,
      "y": 100
    }
  ],
  "links": [
    {
      "id": "9c179bb0-b669-4921-a380-fbd60b0a44ed",
      "name": "Test Map 2",
      "x": 200,
      "y": 200
    }
  ]
}

Property	Type	Description
`id`	String	The map ID.
`name`	String	The map name.
`description`	String	The map description.
`partitions`	String[]	The partition IDs associated with this map.
`type`	String	The map type. Possible values include `local` and `global`.
`imageUrl`	String	The URL of the user-provided map image.
`opacity`	Integer	The image opacity.
`iconSize`	String	The icon size. Possible values include `S`, `M`, and `L`.
`devices`	Object[]	An array of devices and their accompanying coordinates.
`devices.id`	String	The device ID.
`devices.displayName`	Boolean	Whether the device name is displayed alongside the icon.
`devices.x`	Integer	The horizontal pixel coordinate of the device relative to the top left of the image.
`devices.y`	Integer	The vertical pixel coordinate of the device relative to the top left of the image.
`links`	Object[]	An array of linked maps and their accompanying coordinates.
`links.id`	String	The linked map ID.
`links.x`	Integer	The horizontal pixel coordinate of the linked map relative to the top left of the image.
`links.y`	Integer	The vertical pixel coordinate of the linked map relative to the top left of the image.

{
  "id": "0b4078ac-f150-46d2-b320-b0a0544f8bfd",
  "name": "Test Map 1",
  "description": "Test Map 1",
  "type": "global",
  "latitude": 40.5052747,
  "longitude": -111.8931252,
  "zoom": 17,
  "iconSize": "M",
  "devices": [
    {
      "id": "f90bef5c-1a2b-4763-9fc4-f059c6fd55ba",
      "displayName": true,
      "latitude": 40.5052747,
      "longitude": -111.8931252
    }
  ],
  "links": [
    {
      "id": "9c179bb0-b669-4921-a380-fbd60b0a44ed",
      "name": "Test Map 2",
      "latitude": 40.7765786,
      "longitude": -112.0028844
    }
  ]
}

Parameter	Type	Description
`id`	String	The map ID.
`name`	String	The map name.
`description`	String	The map description.
`type`	String	The map type. Possible values include `local` and `global`.
`latitude`	Number	The latitude of the initial center position of the map.
`longitude`	Number	The longitude of the initial center position of the map.
`zoom`	Integer	The initial zoom level of the map.
`iconSize`	String	The icon size. Possible values include `S`, `M`, and `L`.
`devices`	Object[]	An array of devices and their accompanying coordinates.
`devices.id`	String	The device ID.
`devices.displayName`	Boolean	Whether the device name is displayed alongside the icon.
`devices.latitude`	Number	The latitudinal component of the device coordinate.
`devices.longitude`	Number	The longitudinal component of the device coordinate.
`links`	Object[]	An array of linked maps and their accompanying coordinates.
`links.id`	String	The linked map ID.
`links.latitude`	Number	The latitudinal component of the linked map coordinate.
`links.longitude`	Number	The longitudinal component of the linked map coordinate.

Basic Endpoints

Create a map

Request

Local
Global

POST https://systems.pdk.io/{{system_id}}/maps HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Map 1",
  "description": "Test Map 1",
  "partitions": ["619cceb0-ac58-4b15-a8ec-32efcb0476ba"],
  "type": "local",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHgAAAB4CAAAAAAcD2kOAAABZklEQVR4Ae3XAYnDMBTG8RqogBqIgRqogBiYgRiogBqYgRiIgBh4Bj5Rd13yIAs5uHHrGwffH2DNI+MH3cLWCR+KMGHChAkTJkz4tQgTJkyYMGHChAkTJkyYcIqDZDAXlOQevqtLiYPSr+B1GhQH84iztOnaHQDiNGi9AA7txCUrWF1tsYJ7JvwFvq2PlvqeUlJ4qYMyq5/vFoI7X2dBWktTu/v2wnHSm9jfiYAmKXvu53X29aI0dbvfC8enG5kTbGEHzRiednNY9BQd+XJ4DaUDZ27S3C5Xwv3RvLcjL3YwfDubkx2M0MtWMHJYmul1sB/8xKbgVM4mx6m1Kx2tYcjyIRjeFJZtU8qZwar5fF4d5TzhGrj/I7DXQxT0a+0vg9tinrvJnG1g6UcHbGBgn5v1fMAMhuxOlz7jLXCOj6D9+AiTyxMMnitbMp8WCRMmTJgwYcKECRMmTJgwYcKECRMmTPhfwV9kH2srWmFAYQAAAABJRU5ErkJggg==",
  "opacity": 100,
  "devices": [
    {
      "id": "f90bef5c-1a2b-4763-9fc4-f059c6fd55ba",
      "displayName": true,
      "x": 100,
      "y": 100
    }
  ],
  "links": [
    {
      "id": "9c179bb0-b669-4921-a380-fbd60b0a44ed",
      "name": "Test Map 2",
      "x": 200,
      "y": 200
    }
  ]
}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`system_token`	Header	String	Yes	A valid system token.
`name`	Body	String	Yes	The map name. This must be unique within a system.
`description`	Body	String	Yes	The map description. This must be unique within a system.
`partitions`	Body	String[]	Yes	The partition IDs associated with this map.
`type`	Body	String	Yes	The map type. Possible values include `local` and `global`.
`image`	Body	String	Yes	The map image encoded as a data URL.
`opacity`	Body	Integer	No	The image opacity. Adjusting the opacity may help improve the readability of overlaid text. The minimum value is 0 (default) and the maximum value is 100. While not strictly required, this value should always be specified since the image will otherwise be invisible by default.
`iconSize`	Body	String	No	The icon size. Possible values include `S`, `M`, and `L`.
`devices`	Body	Object[]	Yes	An array of devices and their accompanying coordinates.
`devices.id`	Body	String	Yes	The device ID.
`devices.displayName`	Body	Boolean	Yes	Whether the device name should be displayed alongside the icon.
`devices.x`	Body	Integer	Yes	The horizontal pixel coordinate of the device relative to the top left of the image.
`devices.y`	Body	Integer	Yes	The vertical pixel coordinate of the device relative to the top left of the image.
`links`	Body	Object[]	Yes	An array of linked maps and their accompanying coordinates.
`links.id`	Body	String	Yes	The linked map ID.
`links.x`	Body	Integer	Yes	The horizontal pixel coordinate of the linked map relative to the top left of the image.
`links.y`	Body	Integer	Yes	The vertical pixel coordinate of the linked map relative to the top left of the image.

POST https://systems.pdk.io/{{system_id}}/maps HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Map 1",
  "description": "Test Map 1",
  "type": "global",
  "latitude": 40.5052747,
  "longitude": -111.8931252,
  "zoom": 17,
  "devices": [
    {
      "id": "f90bef5c-1a2b-4763-9fc4-f059c6fd55ba",
      "displayName": true,
      "latitude": 40.5052747,
      "longitude": -111.8931252
    }
  ],
  "links": [
    {
      "id": "9c179bb0-b669-4921-a380-fbd60b0a44ed",
      "name": "Test Map 2",
      "latitude": 40.7765786,
      "longitude": -112.0028844
    }
  ]
}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`system_token`	Header	String	Yes	A valid system token.
`name`	Body	String	Yes	The map name. This must be unique within a system.
`description`	Body	String	Yes	The map description. This must be unique within a system.
`type`	Body	String	Yes	The map type. Possible values include `local` and `global`.
`latitude`	Body	Number	Yes	The latitude of the initial center position of the map.
`longitude`	Body	Number	Yes	The longitude of the initial center position of the map.
`zoom`	Body	Integer	Yes	The initial zoom level of the map. The minimum value is `0` and the maximum value is `19`.
`iconSize`	Body	String	No	The icon size. Possible values include `S`, `M`, and `L`.
`devices`	Body	Object[]	Yes	An array of devices and their accompanying coordinates.
`devices.id`	Body	String	Yes	The device ID.
`devices.displayName`	Body	Boolean	Yes	Whether the device name should be displayed alongside the icon.
`devices.latitude`	Body	Number	Yes	The latitudinal component of the device coordinate.
`devices.longitude`	Body	Number	Yes	The longitudinal component of the device coordinate.
`links`	Body	Object[]	Yes	An array of linked maps and their accompanying coordinates.
`links.id`	Body	String	Yes	The linked map ID.
`links.latitude`	Body	Number	Yes	The latitudinal component of the linked map coordinate.
`links.longitude`	Body	Number	Yes	The longitudinal component of the linked map coordinate.

Response

The response contains the ID of the newly created map object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "0b4078ac-f150-46d2-b320-b0a0544f8bfd"
}

Retrieve a map

Request

GET https://systems.pdk.io/{{system_id}}/maps/{{map_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`map_id`	Path	String	Yes	The map ID.
`system_token`	Header	String	Yes	A valid system token.

Response

The response contains a map object.

Local
Global

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "0b4078ac-f150-46d2-b320-b0a0544f8bfd",
  "name": "Test Map 1",
  "description": "Test Map 1",
  "partitions": ["619cceb0-ac58-4b15-a8ec-32efcb0476ba"],
  "type": "local",
  "imageUrl": "http://systems.pdk.io/images/22ba2c70-631a-11ee-90fc-598e4a89e620",
  "opacity": 100,
  "iconSize": "M",
  "devices": [
    {
      "id": "f90bef5c-1a2b-4763-9fc4-f059c6fd55ba",
      "displayName": true,
      "x": 100,
      "y": 100
    }
  ],
  "links": [
    {
      "id": "9c179bb0-b669-4921-a380-fbd60b0a44ed",
      "name": "Test Map 2",
      "x": 200,
      "y": 200
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "0b4078ac-f150-46d2-b320-b0a0544f8bfd",
  "name": "Test Map 1",
  "description": "Test Map 1",
  "type": "global",
  "latitude": 40.5052747,
  "longitude": -111.8931252,
  "zoom": 17,
  "iconSize": "M",
  "devices": [
    {
      "id": "f90bef5c-1a2b-4763-9fc4-f059c6fd55ba",
      "displayName": true,
      "latitude": 40.5052747,
      "longitude": -111.8931252
    }
  ],
  "links": [
    {
      "id": "9c179bb0-b669-4921-a380-fbd60b0a44ed",
      "name": "Test Map 2",
      "latitude": 40.7765786,
      "longitude": -112.0028844
    }
  ]
}

Update a map

Request

Local
Global

PUT https://systems.pdk.io/{{system_id}}/maps/{{map_id}} HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Map 1",
  "description": "Test Map 1",
  "partitions": ["619cceb0-ac58-4b15-a8ec-32efcb0476ba"],
  "type": "local",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHgAAAB4CAAAAAAcD2kOAAABZklEQVR4Ae3XAYnDMBTG8RqogBqIgRqogBiYgRiogBqYgRiIgBh4Bj5Rd13yIAs5uHHrGwffH2DNI+MH3cLWCR+KMGHChAkTJkz4tQgTJkyYMGHChAkTJkyYcIqDZDAXlOQevqtLiYPSr+B1GhQH84iztOnaHQDiNGi9AA7txCUrWF1tsYJ7JvwFvq2PlvqeUlJ4qYMyq5/vFoI7X2dBWktTu/v2wnHSm9jfiYAmKXvu53X29aI0dbvfC8enG5kTbGEHzRiednNY9BQd+XJ4DaUDZ27S3C5Xwv3RvLcjL3YwfDubkx2M0MtWMHJYmul1sB/8xKbgVM4mx6m1Kx2tYcjyIRjeFJZtU8qZwar5fF4d5TzhGrj/I7DXQxT0a+0vg9tinrvJnG1g6UcHbGBgn5v1fMAMhuxOlz7jLXCOj6D9+AiTyxMMnitbMp8WCRMmTJgwYcKECRMmTJgwYcKECRMmTPhfwV9kH2srWmFAYQAAAABJRU5ErkJggg==",
  "opacity": 100,
  "devices": [
    {
      "id": "f90bef5c-1a2b-4763-9fc4-f059c6fd55ba",
      "displayName": true,
      "x": 100,
      "y": 100
    }
  ],
  "links": [
    {
      "id": "9c179bb0-b669-4921-a380-fbd60b0a44ed",
      "name": "Test Map 2",
      "x": 200,
      "y": 200
    }
  ]
}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`map_id`	Path	String	Yes	The map ID.
`system_token`	Header	String	Yes	A valid system token.
`name`	Body	String	Yes	The map name. This must be unique within a system.
`description`	Body	String	Yes	The map description. This must be unique within a system.
`partitions`	Body	String[]	Yes	The partition IDs associated with this map.
`type`	Body	String	Yes	The map type. Possible values include `local` and `global`.
`image`	Body	String	Yes	The map image encoded as a data URL.
`opacity`	Body	Integer	No	The image opacity. Adjusting the opacity may help improve the readability of overlaid text. The minimum value is 0 (default) and the maximum value is 100. While not strictly required, this value should always be specified since the image will otherwise be invisible by default.
`iconSize`	Body	String	No	The icon size. Possible values include `S`, `M`, and `L`.
`devices`	Body	Object[]	Yes	An array of devices and their accompanying coordinates.
`devices.id`	Body	String	Yes	The device ID.
`devices.displayName`	Body	Boolean	Yes	Whether the device name should be displayed alongside the icon.
`devices.x`	Body	Integer	Yes	The horizontal pixel coordinate of the device relative to the top left of the image.
`devices.y`	Body	Integer	Yes	The vertical pixel coordinate of the device relative to the top left of the image.
`links`	Body	Object[]	Yes	An array of linked maps and their accompanying coordinates.
`links.id`	Body	String	Yes	The linked map ID.
`links.x`	Body	Integer	Yes	The horizontal pixel coordinate of the linked map relative to the top left of the image.
`links.y`	Body	Integer	Yes	The vertical pixel coordinate of the linked map relative to the top left of the image.

PUT https://systems.pdk.io/{{system_id}}/maps/{{map_id}} HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Map 1",
  "description": "Test Map 1",
  "type": "global",
  "latitude": 40.5052747,
  "longitude": -111.8931252,
  "zoom": 17,
  "devices": [
    {
      "id": "f90bef5c-1a2b-4763-9fc4-f059c6fd55ba",
      "displayName": true,
      "latitude": 40.5052747,
      "longitude": -111.8931252
    }
  ],
  "links": [
    {
      "id": "9c179bb0-b669-4921-a380-fbd60b0a44ed",
      "name": "Test Map 2",
      "latitude": 40.7765786,
      "longitude": -112.0028844
    }
  ]
}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`map_id`	Path	String	Yes	The map ID.
`system_token`	Header	String	Yes	A valid system token.
`name`	Body	String	Yes	The map name. This must be unique within a system.
`description`	Body	String	Yes	The map description. This must be unique within a system.
`type`	Body	String	Yes	The map type. Possible values include `local` and `global`.
`latitude`	Body	Number	Yes	The latitude of the initial center position of the map.
`longitude`	Body	Number	Yes	The longitude of the initial center position of the map.
`zoom`	Body	Integer	Yes	The initial zoom level of the map. The minimum value is `0` and the maximum value is `19`.
`iconSize`	Body	String	No	The icon size. Possible values include `S`, `M`, and `L`.
`devices`	Body	Object[]	Yes	An array of devices and their accompanying coordinates.
`devices.id`	Body	String	Yes	The device ID.
`devices.displayName`	Body	Boolean	Yes	Whether the device name should be displayed alongside the icon.
`devices.latitude`	Body	Number	Yes	The latitudinal component of the device coordinate.
`devices.longitude`	Body	Number	Yes	The longitudinal component of the device coordinate.
`links`	Body	Object[]	Yes	An array of linked maps and their accompanying coordinates.
`links.id`	Body	String	Yes	The linked map ID.
`links.latitude`	Body	Number	Yes	The latitudinal component of the linked map coordinate.
`links.longitude`	Body	Number	Yes	The longitudinal component of the linked map coordinate.

Response

HTTP/1.1 204 No Content

Delete a map

Request

DELETE https://systems.pdk.io/{{system_id}}/maps/{{map_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`map_id`	Path	String	Yes	The map ID.
`system_token`	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content

List all maps

Request

GET https://systems.pdk.io/{{system_id}}/maps HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`system_token`	Header	String	Yes	A valid system token.

Response

The response contains an array of map objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "0b4078ac-f150-46d2-b320-b0a0544f8bfd",
    "name": "Test Map 1",
    "description": "Test Map 1",
    "partitions": ["619cceb0-ac58-4b15-a8ec-32efcb0476ba"],
    "type": "local",
    "imageUrl": "http://systems.pdk.io/images/22ba2c70-631a-11ee-90fc-598e4a89e620",
    "opacity": 100,
    "iconSize": "M",
    "devices": [
      {
        "id": "f90bef5c-1a2b-4763-9fc4-f059c6fd55ba",
        "displayName": true,
        "x": 100,
        "y": 100
      }
    ],
    "links": [
      {
        "id": "9c179bb0-b669-4921-a380-fbd60b0a44ed",
        "name": "Test Map 2",
        "x": 200,
        "y": 200
      }
    ]
  }
]

Introduction​

The map object​

Basic Endpoints​

Create a map​

Request

Response

Retrieve a map​

Request

Response

Update a map​

Request

Response

Delete a map​

Request

Response

List all maps​

Request

Response

Introduction

The map object

Basic Endpoints

Create a map

Retrieve a map

Update a map

Delete a map

List all maps