# Api introduction

Domain request model includes Api and socket(include WeChat socket)

| Type                            | URL                                                       |
| ------------------------------- | --------------------------------------------------------- |
| RESTful Api (api-host)          | <https://api-toilet.seeed.cc>                             |
| Web Socket (skt-host)           | [https://ws-toilet.seeed.cc](https://api-toilet.seeed.cc) |
| WeChat applet socket (skt-host) | wss\://ws-toilet.seeed.cc                                 |

The introduction of the RESTful, [click here](https://doc.api.sensecap.seeed.cc/doc/http-api-access-guides/http-methods)

The introduction to requests and responses, [click here](https://doc.api.sensecap.seeed.cc/doc/http-api-access-guides/untitled)

The introduction of  web socket:

* server use socket.io.
  * socket.io [doc-server](https://socket.io/docs/server-api)
  * socket.io [doc-client](https://socket.io/docs/client-api)

The introduction of the API call relationship

> 1. Get all WC position data for your organization or company via the API - The list of position
> 2. Get all WC cubicles data by the position ID, via the API - The list of cubicles
> 3. Keep long connection for real-time data of the cubicles or meeting rooms via the Socket

## Api - The list of positions

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

Get a list of all the toilet positions in a company or organization.

#### Path Parameters

| Name | Type   | Description                                                                                |
| ---- | ------ | ------------------------------------------------------------------------------------------ |
| bloc | string | <p>the unique flag for the company or organization. <br>for example: bloc=361832720401</p> |

#### Query Parameters

| Name | Type   | Description                                                                                       |
| ---- | ------ | ------------------------------------------------------------------------------------------------- |
| type | string | <p>type=1 , get positions list of the WC.<br>type=2, get positions list of the meeting rooms.</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 - The list of cubicles

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

Get a list of all the toilet cubicles which the position selected.

#### Path Parameters

| Name         | Type   | Description                                                                            |
| ------------ | ------ | -------------------------------------------------------------------------------------- |
| position\_id | string | <p>the unique id from \<The list of positions> api.<br>for example: 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 - The list of meeting rooms

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

Get a list of all the meeting rooms which the position selected.\
A meeting room maybe includes more than one sensor.

#### Path Parameters

| Name         | Type   | Description                                                                            |
| ------------ | ------ | -------------------------------------------------------------------------------------- |
| position\_id | string | <p>the unique id from \<The list of positions> api.<br>for example: 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 - Get the real-time status (cubicles or meeting rooms)

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

Get real-time status which the position selected.

#### Path Parameters

| Name | Type   | Description                                                          |
| ---- | ------ | -------------------------------------------------------------------- |
| rn   | string | <p>room name = position\_id, <br>for example:  the (client demo)</p> |

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

```javascript
[
  {
    "key": "5C8DB3C40626014921540C3581C16306", // 当eui属于会议室，会返回该key
    "eui": "sd45fe32", // 设备编号
	"use_time": "-1" // 时间秒，大于0使用时长，小于0空闲时长
  }
]
```

{% endtab %}
{% endtabs %}

> client demo (nodejs)
>
> ```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 by the email 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/master.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.