Version: 1.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 cloud node 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 cloud node may only contain one global map.

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

The map object

Local
Global

{
  "id": 1,
  "name": "Test Map 1",
  "description": "Test Map 1",
  "partitions": [0],
  "type": "local",
  "imageUrl": "https://panel-1234ABC.pdk.io:443/images/40968370-e835-11ed-adcb-8d19f7185405",
  "opacity": 100,
  "iconSize": "M",
  "doors": [
    {
      "id": 1,
      "displayName": true,
      "x": 100,
      "y": 100
    }
  ],
  "links": [
    {
      "id": 2,
      "name": "Test Map 2",
      "x": 200,
      "y": 200
    }
  ]
}

Property	Type	Description
`id`	Integer	The map ID.
`name`	String	The map name.
`description`	String	The map description.
`partitions`	Integer[]	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`.
`doors`	Object[]	An array of devices and their accompanying coordinates.
`doors.id`	Integer	The device ID.
`doors.displayName`	Boolean	Whether the device name is displayed alongside the icon.
`doors.x`	Integer	The horizontal pixel coordinate of the device relative to the top left of the image.
`doors.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`	Integer	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": 1,
  "name": "Test Map 1",
  "description": "Test Map 1",
  "type": "global",
  "latitude": 40.5052747,
  "longitude": -111.8931252,
  "zoom": 17,
  "iconSize": "M",
  "doors": [
    {
      "id": 1,
      "displayName": true,
      "latitude": 40.5052747,
      "longitude": -111.8931252
    }
  ],
  "links": [
    {
      "id": 2,
      "name": "Test Map 2",
      "latitude": 40.7765786,
      "longitude": -112.0028844
    }
  ]
}

Parameter	Type	Description
`id`	Integer	The map ID.
`name`	String	The map name.
`description`	String	The map description.
`partitions`	Integer[]	The partition IDs associated with this map.
`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`.
`doors`	Object[]	An array of devices and their accompanying coordinates.
`doors.id`	Integer	The device ID.
`doors.displayName`	Boolean	Whether the device name is displayed alongside the icon.
`doors.latitude`	Number	The latitudinal component of the device coordinate.
`doors.longitude`	Number	The longitudinal component of the device coordinate.
`links`	Object[]	An array of linked maps and their accompanying coordinates.
`links.id`	Integer	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://panel-{{panel_id}}.pdk.io/api/maps HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "name": "Test Map 1",
  "description": "Test Map 1",
  "partitions": [0],
  "type": "local",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHgAAAB4CAAAAAAcD2kOAAABZklEQVR4Ae3XAYnDMBTG8RqogBqIgRqogBiYgRiogBqYgRiIgBh4Bj5Rd13yIAs5uHHrGwffH2DNI+MH3cLWCR+KMGHChAkTJkz4tQgTJkyYMGHChAkTJkyYcIqDZDAXlOQevqtLiYPSr+B1GhQH84iztOnaHQDiNGi9AA7txCUrWF1tsYJ7JvwFvq2PlvqeUlJ4qYMyq5/vFoI7X2dBWktTu/v2wnHSm9jfiYAmKXvu53X29aI0dbvfC8enG5kTbGEHzRiednNY9BQd+XJ4DaUDZ27S3C5Xwv3RvLcjL3YwfDubkx2M0MtWMHJYmul1sB/8xKbgVM4mx6m1Kx2tYcjyIRjeFJZtU8qZwar5fF4d5TzhGrj/I7DXQxT0a+0vg9tinrvJnG1g6UcHbGBgn5v1fMAMhuxOlz7jLXCOj6D9+AiTyxMMnitbMp8WCRMmTJgwYcKECRMmTJgwYcKECRMmTPhfwV9kH2srWmFAYQAAAABJRU5ErkJggg==",
  "opacity": 100,
  "doors": [
    {
      "id": 1,
      "displayName": true,
      "x": 100,
      "y": 100
    }
  ],
  "links": [
    {
      "id": 2,
      "name": "Test Map 2",
      "x": 200,
      "y": 200
    }
  ]
}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`panel_token`	Header	String	Yes	A valid panel token.
`name`	Body	String	Yes	The map name. This must be unique within a cloud node.
`description`	Body	String	Yes	The map description. This must be unique within a cloud node.
`partitions`	Body	Integer[]	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`.
`doors`	Body	Object[]	Yes	An array of devices and their accompanying coordinates.
`doors.id`	Body	Integer	Yes	The device ID.
`doors.displayName`	Body	Boolean	Yes	Whether the device name should be displayed alongside the icon.
`doors.x`	Body	Integer	Yes	The horizontal pixel coordinate of the device relative to the top left of the image.
`doors.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	Integer	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://panel-{{panel_id}}.pdk.io/api/maps HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "name": "Test Map 1",
  "description": "Test Map 1",
  "type": "global",
  "latitude": 40.5052747,
  "longitude": -111.8931252,
  "zoom": 17,
  "doors": [
    {
      "id": 1,
      "displayName": true,
      "latitude": 40.5052747,
      "longitude": -111.8931252
    }
  ],
  "links": [
    {
      "id": 2,
      "name": "Test Map 2",
      "latitude": 40.7765786,
      "longitude": -112.0028844
    }
  ]
}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`panel_token`	Header	String	Yes	A valid panel token.
`name`	Body	String	Yes	The map name. This must be unique within a cloud node.
`description`	Body	String	Yes	The map description. This must be unique within a cloud node.
`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`.
`doors`	Body	Object[]	Yes	An array of devices and their accompanying coordinates.
`doors.id`	Body	Integer	Yes	The device ID.
`doors.displayName`	Body	Boolean	Yes	Whether the device name should be displayed alongside the icon.
`doors.latitude`	Body	Number	Yes	The latitudinal component of the device coordinate.
`doors.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	Integer	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": 1
}

Retrieve a map

Request

GET https://panel-{{panel_id}}.pdk.io/api/maps/{{map_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`map_id`	Path	Integer	Yes	The map ID.
`panel_token`	Header	String	Yes	A valid panel token.

Response

The response contains a map object.

Local
Global

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

{
  "id": 1,
  "name": "Test Map 1",
  "description": "Test Map 1",
  "partitions": [0],
  "type": "local",
  "imageUrl": "https://panel-1234ABC.pdk.io:443/images/40968370-e835-11ed-adcb-8d19f7185405",
  "opacity": 100,
  "iconSize": "M",
  "doors": [
    {
      "id": 1,
      "displayName": true,
      "x": 100,
      "y": 100
    }
  ],
  "links": [
    {
      "id": 2,
      "name": "Test Map 2",
      "x": 200,
      "y": 200
    }
  ]
}

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

{
  "id": 1,
  "name": "Test Map 1",
  "description": "Test Map 1",
  "type": "global",
  "latitude": 40.5052747,
  "longitude": -111.8931252,
  "zoom": 17,
  "iconSize": "M",
  "doors": [
    {
      "id": 1,
      "displayName": true,
      "latitude": 40.5052747,
      "longitude": -111.8931252
    }
  ],
  "links": [
    {
      "id": 2,
      "name": "Test Map 2",
      "latitude": 40.7765786,
      "longitude": -112.0028844
    }
  ]
}

Update a map

Request

Local
Global

PUT https://panel-{{panel_id}}.pdk.io/api/maps/{{map_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "name": "Test Map 1",
  "description": "Test Map 1",
  "partitions": [0],
  "type": "local",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHgAAAB4CAAAAAAcD2kOAAABZklEQVR4Ae3XAYnDMBTG8RqogBqIgRqogBiYgRiogBqYgRiIgBh4Bj5Rd13yIAs5uHHrGwffH2DNI+MH3cLWCR+KMGHChAkTJkz4tQgTJkyYMGHChAkTJkyYcIqDZDAXlOQevqtLiYPSr+B1GhQH84iztOnaHQDiNGi9AA7txCUrWF1tsYJ7JvwFvq2PlvqeUlJ4qYMyq5/vFoI7X2dBWktTu/v2wnHSm9jfiYAmKXvu53X29aI0dbvfC8enG5kTbGEHzRiednNY9BQd+XJ4DaUDZ27S3C5Xwv3RvLcjL3YwfDubkx2M0MtWMHJYmul1sB/8xKbgVM4mx6m1Kx2tYcjyIRjeFJZtU8qZwar5fF4d5TzhGrj/I7DXQxT0a+0vg9tinrvJnG1g6UcHbGBgn5v1fMAMhuxOlz7jLXCOj6D9+AiTyxMMnitbMp8WCRMmTJgwYcKECRMmTJgwYcKECRMmTPhfwV9kH2srWmFAYQAAAABJRU5ErkJggg==",
  "opacity": 100,
  "doors": [
    {
      "id": 1,
      "displayName": true,
      "x": 100,
      "y": 100
    }
  ],
  "links": [
    {
      "id": 2,
      "name": "Test Map 2",
      "x": 200,
      "y": 200
    }
  ]
}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`map_id`	Path	Integer	Yes	The map ID.
`panel_token`	Header	String	Yes	A valid panel token.
`name`	Body	String	Yes	The map name. This must be unique within a cloud node.
`description`	Body	String	Yes	The map description. This must be unique within a cloud node.
`partitions`	Body	Integer[]	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`.
`doors`	Body	Object[]	Yes	An array of devices and their accompanying coordinates.
`doors.id`	Body	Integer	Yes	The device ID.
`doors.displayName`	Body	Boolean	Yes	Whether the device name should be displayed alongside the icon.
`doors.x`	Body	Integer	Yes	The horizontal pixel coordinate of the device relative to the top left of the image.
`doors.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	Integer	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://panel-{{panel_id}}.pdk.io/api/maps/{{map_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "name": "Test Map 1",
  "description": "Test Map 1",
  "type": "global",
  "latitude": 40.5052747,
  "longitude": -111.8931252,
  "zoom": 17,
  "doors": [
    {
      "id": 1,
      "displayName": true,
      "latitude": 40.5052747,
      "longitude": -111.8931252
    }
  ],
  "links": [
    {
      "id": 2,
      "name": "Test Map 2",
      "latitude": 40.7765786,
      "longitude": -112.0028844
    }
  ]
}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`map_id`	Path	Integer	Yes	The map ID.
`panel_token`	Header	String	Yes	A valid panel token.
`name`	Body	String	Yes	The map name. This must be unique within a cloud node.
`description`	Body	String	Yes	The map description. This must be unique within a cloud node.
`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`.
`doors`	Body	Object[]	Yes	An array of devices and their accompanying coordinates.
`doors.id`	Body	Integer	Yes	The device ID.
`doors.displayName`	Body	Boolean	Yes	Whether the device name should be displayed alongside the icon.
`doors.latitude`	Body	Number	Yes	The latitudinal component of the device coordinate.
`doors.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	Integer	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://panel-{{panel_id}}.pdk.io/api/maps/{{map_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`map_id`	Path	Integer	Yes	The map ID.
`panel_token`	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content

List all maps

Request

GET https://panel-{{panel_id}}.pdk.io/api/maps HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`panel_token`	Header	String	Yes	A valid panel token.

Response

The response contains an array of map objects.

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

[
  {
    "id": 1,
    "name": "Test Map 1",
    "description": "Test Map 1",
    "partitions": [0],
    "type": "local",
    "imageUrl": "https://panel-1234ABC.pdk.io:443/images/40968370-e835-11ed-adcb-8d19f7185405",
    "opacity": 100,
    "iconSize": "M",
    "doors": [
      {
        "id": 1,
        "displayName": true,
        "x": 100,
        "y": 100
      }
    ],
    "links": [
      {
        "id": 3,
        "name": "Test Map 3",
        "x": 200,
        "y": 200
      }
    ]
  },
  {
    "id": 2,
    "name": "Test Map 2",
    "description": "Test Map 2",
    "type": "global",
    "latitude": 40.5052747,
    "longitude": -111.8931252,
    "zoom": 17,
    "iconSize": "M",
    "doors": [
      {
        "id": 2,
        "displayName": true,
        "latitude": 40.5052747,
        "longitude": -111.8931252
      }
    ],
    "links": [
      {
        "id": 4,
        "name": "Test Map 4",
        "latitude": 40.7765786,
        "longitude": -112.0028844
      }
    ]
  }
]

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