> For the complete documentation index, see [llms.txt](https://toilet.doc.seeed.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://toilet.doc.seeed.cc/api-jie-shao.md).

# Api 介绍

域名host介绍

| 类型                              | 地址                             |
| ------------------------------- | ------------------------------ |
| RESTful Api（api-host）           | ​<https://api-toilet.seeed.cc> |
| Web Socket（skt-host）            | <https://ws-toilet.seeed.cc>   |
| WeChat applet Socket （skt-host） | wss\://ws-toilet.seeed.cc      |

RESTful Api的介绍请参考[这里](https://doc.api.sensecap.seeed.cc/doc/http-api-access-guides/http-methods)

RESTful Api的入参及返回结构请参考[这里](https://doc.api.sensecap.seeed.cc/doc/http-api-access-guides/untitled)

Web Socket的介绍：

* 服务端采用socket.io构建
* socket.io [doc-server](https://socket.io/docs/server-api/)
* socket.io [doc-client](https://socket.io/docs/client-api)

Api及Socket的调用关系介绍

* 获取某一个公司或者组织的区域列表，得到区域id（position\_id）
* 通过区域id（position\_id）获取该区域下的所有会议室or卫生间列表
* 通过区域id（position\_id）建立以区域id为房间（socket.io room）的长连接

## Api - 获取区域列表

<mark style="color:blue;">`GET`</mark> `{api-host}/v1/lists/positions/:bloc`

#### Path Parameters

| Name | Type   | Description                                       |
| ---- | ------ | ------------------------------------------------- |
| bloc | string | <p>代表公司or组织的唯一flag<br>如某组织A bloc=361832720401</p> |

#### Query Parameters

| Name | Type   | Description                                   |
| ---- | ------ | --------------------------------------------- |
| type | string | <p>type=1，获取卫生间的区域列表<br>type=2，获取会议室的区域列表</p> |

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

```
{
    "code": "0",
    "data": [
        {
            "id": "32", //  position id, the unique id for the location of a toilet
            "company": "Seeed", // the name of company or organization
            "position": "国际E城G栋9楼" // the name of the toilet
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Api - 获取卫生间列表

<mark style="color:blue;">`GET`</mark> `{api-host}/v1/lists/cubicles/:position_id`

&#x20;获取某一个区域下的卫生间列表

#### Path Parameters

| Name         | Type   | Description                                |
| ------------ | ------ | ------------------------------------------ |
| position\_id | string | <p>通过调用区域列表获取的唯一id<br>如 position\_id=1</p> |

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

```
{
    "code": "0",
    "data": [
        {
            "eui": "sd45fe32", // 设备编号
            "gender": "1", // 性别：1男，2女，3其它（如残疾等）
            "shape": "1", // 隔间马桶形状：1蹲位，2坐型，3其它
            "number": "1", // 隔间编号，如1号隔间
            "use_time": "91" // 单位秒，大于0表示正在使用多少秒，小于0表示空闲多少秒
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Api - 获取会议室列表

<mark style="color:blue;">`GET`</mark> `{api-host}/v1/lists/meetingrooms/:position_id`

&#x20;获取某一区域下的会议室列表

#### Path Parameters

| Name         | Type   | Description                              |
| ------------ | ------ | ---------------------------------------- |
| position\_id | string | <p>通过区域列表获取的唯一id<br>如 position\_id=2</p> |

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

```
{
    "code": "0",
    "data": [
        {
            "key": "5C8DB3C40626014921540C3581C16306", // 每个会议室有唯一key，该key可能包含多个sensor
            "shape": "3", // 会议室形状，1小会议室，2中型会议室，3大型会议室
            "number": "B区大会议室",
            "eui": [
                {
                    "eui": "6df54c4d",
                    "use_time": "-54637"
                }
            ]
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Socket - 获取实时数据（会议室or卫生间）

<mark style="color:blue;">`GET`</mark> `{skt-api}/v1`

&#x20;通过socket长连接，获取传感器的实时数据推送

#### Path Parameters

| Name | Type   | Description                                                                    |
| ---- | ------ | ------------------------------------------------------------------------------ |
| rn   | string | <p>room name，房间号<br>服务端以一个区域为一个房间单位<br>rn等值于position\_id，如获取到的区域id=3，则rn=3</p> |

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

```
```

{% endtab %}
{% endtabs %}

> client demo (nodejs)
>
> * 示例中为目前全部方法，部分方法包含callback，调用时需要额外注意，否则会请求失败。
>
> ```javascript
> const io = require('socket.io-client')
>
> // room name
> // the room name is the position_id, get position_id from the api (https://toilet.doc.seeed.cc/ - The list of positions)
> let rn = process.argv[2] || 10
>
> // 客户端需要做好重连策略，如服务端重启服务后，需要客户端主动再连接服务端。
> const skt = io(`https://ws-toilet.seeed.cc/v1`, {
>   query: {
>     // 参数 token
>     token: 'toilet'
>   }
> })
>
> /**
>  * @event connect
>  */
> skt.on('connect', () => {
>   console.log('connect successfully, ', ' Socket ID: ', skt.id)
> })
>
> /**
>  * 加入房间，服务端消息是基于房间发送，加入房间后就能收到消息
>  * @event joinRoom
>  * @param rn: room name
>  * @callback status: err|true
>  */
> skt.emit('joinRoom', rn, function (status) {
>   if (status !== true) {
>     return
>   }
>
>   /**
>    * 离开房间（客户端需要保持长连接的时候，则不需要离开房间）
>    * @event leaveRoom
>    * @param rn: room name
>    * @function status: err|true
>    */
>   skt.emit('leaveRoom', rn, function (status) {
>     if (status !== true) {
>       return
>     }
>
>     // 关闭连接
>     skt.close()
>     skt.disconnect()
>   })
> })
>
> /**
>  * 最新的数据
>  * @event latestCubicle
>  */
> skt.on('latestCubicle', (data) => {
>   console.log('latest cubicle:', data)
> })
>
> /**
>  * 'transport error'
>  * 'server namespace disconnect'
>  */
> skt.on('disconnect', (reason) => {
>   skt.close()
>   console.log('disconnect', reason)
> })
>
> // normal message
> skt.on('message', (data) => {
>   console.log('message:', data)
> })
>
> skt.on('close', function (err) {
>   skt.close()
>   console.log('close', err)
> })
>
> skt.on('error', function (err) {
>   console.log('error', err)
> })
> ```

> If you have any questions, Please contact to `kevin.yang@seeed.cc`