# Zones

The `/zones` endpoint provide access to discover, create and manage zones available. For more information on the role that zones play, see:

{% content-ref url="../../key-concepts/zones" %}
[zones](https://engine.place.technology/key-concepts/zones)
{% endcontent-ref %}

## Model <a href="#model" id="model"></a>

| Attribute   | Type      | Description                                                                      |
| ----------- | --------- | -------------------------------------------------------------------------------- |
| id          | `string`  | Unique ID the represents the zone.                                               |
| name        | `string`  | Human readable name.                                                             |
| description | `string`  | Long form description of the zone.                                               |
| tags        | `string`  | Tags that provide context for the zone use. E.g. `org`, `buidling`, `level`.     |
| settings    | `object`  | JSON object containing configuration linked to this zone.                        |
| triggers    | `array`   | List of trigger ID's to be applied to all systems that associate with this zone. |
| created\_at | `integer` | Timestamp of creation.                                                           |

## Discovery

## Search

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/zones`

List or search for zones.

#### Query Parameters

| Name   | Type    | Description                         |
| ------ | ------- | ----------------------------------- |
| q      | string  | A search filter to apply.           |
| limit  | integer | (default 20) Max results to return. |
| offset | integer | The offset within the result set.   |
| tags   | string  | Return zones of this tag only.      |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "total": 3,
  "results": [
    {
        "name": "ACA",
        "description": null,
        "tags": "org",
        "settings": {
            "discovery_info": {
                "buildings": [
                    {
                        "name": "Bourke St",
                        "zone_id": "zone-oOj4O_ijKl"
                    }
                ]
            }
        },
        "triggers": [],
        "created_at": 1555995992,
        "id": "zone-oOj2lGgszq"
    },
    {
        "name": "Bourke St",
        "description": null,
        "tags": "building",
        "settings": {
            "discovery_info": {
                "levels": [
                    {
                        "level_id": "zone-oOj57Msk19",
                        "level_name": "Level 1",
                        "map_url": "assets/maps/level_01.svg"
                    }
                ]
            }
        },
        "triggers": [],
        "created_at": 1555996004,
        "id": "zone-oOj4O_ijKl"
    },
    {
        "name": "Level 1",
        "description": null,
        "tags": "level",
        "settings": {},
        "triggers": [],
        "created_at": 1555996010,
        "id": "zone-oOj57Msk19"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Queries default to searching for any of the entered terms (words). A small query language provides the ability to structure complex queries.

| Operator    | Action                                            |                       |
| ----------- | ------------------------------------------------- | --------------------- |
| `+`         | Matches both terms.                               |                       |
| \`          | \`                                                | Matches either terms. |
| `-`         | Negates a single token.                           |                       |
| `"`         | Wraps tokens to form a phrase.                    |                       |
| `(` and `)` | Provide precedence.                               |                       |
| `~N`        | Specifies edit distance (fuzziness) after a word. |                       |
| `~N`        | Specifies slop amount (deviation) after a phrase. |                       |

## Management

## Create

<mark style="color:green;">`POST`</mark> `https://example.com/api/control/zones`

Defines a new zone.

#### Request Body

| Name        | Type   | Description |
| ----------- | ------ | ----------- |
| name        | string |             |
| description | string |             |
| tags        | string |             |
| settings    | object |             |
| triggers    | array  |             |

{% tabs %}
{% tab title="200 Zone created." %}

```javascript
{
    "name": "ACA",
    "description": null,
    "tags": "org",
    "settings": {},
    "triggers": [],
    "created_at": 1555995992,
    "id": "zone-oOj2lGgszq"
}
```

{% endtab %}
{% endtabs %}

## Retrieve

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/zones/{id}`

Lookup an existing zone.

#### Path Parameters

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| id   | string | ID of the zone to retrieve. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "name": "ACA",
    "description": null,
    "tags": "org",
    "settings": {
        "discovery_info": {
            "buildings": [
                {
                    "name": "Bourke St",
                    "zone_id": "zone-oOj4O_ijKl"
                }
            ]
        }
    },
    "triggers": [],
    "created_at": 1555995992,
    "id": "zone-oOj2lGgszq"
}
```

{% endtab %}
{% endtabs %}

## Update

<mark style="color:orange;">`PUT`</mark> `https://example.com/api/control/zones/{id}`

Updates metadata associated with a zone.

#### Path Parameters

| Name | Type   | Description               |
| ---- | ------ | ------------------------- |
| id   | string | ID of the zone to update. |

#### Request Body

| Name        | Type   | Description |
| ----------- | ------ | ----------- |
| name        | string |             |
| description | string |             |
| tags        | string |             |
| settings    | object |             |
| triggers    | array  |             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "name": "ACA",
    "description": null,
    "tags": "org",
    "settings": {
        "discovery_info": {
            "buildings": [
                {
                    "name": "Bourke St",
                    "zone_id": "zone-oOj4O_ijKl"
                }
            ]
        }
    },
    "triggers": [],
    "created_at": 1555995992,
    "id": "zone-oOj2lGgszq"
}
```

{% endtab %}
{% endtabs %}

## Delete

<mark style="color:red;">`DELETE`</mark> `https://example.com/api/control/zones/{id}`

Removes a zone.

#### Path Parameters

| Name | Type   | Description               |
| ---- | ------ | ------------------------- |
| id   | string | ID of the zone to remove. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}