# 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`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://toilet.doc.seeed.cc/api-jie-shao.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.