---
# System prepended metadata

title: API Document
tags: [Speaker]

---

---
tags: Speaker
title: API Document
---
# API Document
> For features or data that need to be transfer to 「伺服器」 or 「前端」 , please specify the variable and format needed to call your API, and the format of the returned data.

> Or the API 「伺服器」 has to provide, specify the data needed and the expected arguments format.
team 伺服器 can also add comments or modify the content. 
<!-- Start of dual speaker 
## 雙聲道藍牙資訊請求(GET)
- 請求路線：音箱 -> 伺服器
### Request Body 
| Parameters      | Value                                        | 
| --------------- | -------------------------------------------- |
| speakerNickname | **string** <br> 使用音箱的暱稱作為查詢的依據 |
### Response Body
| Data name           | Value                                         |
| ------------------- | --------------------------------------------- |
| speakerID           | **HashID** <br> The immutable ID of the speaker | 
| speakerBluetoothMAC | **String: 12 character**                      |

## 雙聲道模式查詢(GET)
- 請求路線：伺服器 -> 音箱
### Response Body
| Data name       | Value       |
| --------------- | ----------- |
| dualChannelMode | **Boolean** |


## 藍芽遠端開啟並連接（伺服器端）(POST)
- 請求路線：音箱 -> 伺服器
### Request Body
| Parameters          | Value                    | 
| ------------------- | ------------------------ |
| speakerBluetoothMAC | **String: 12 character** |
### Response Body
| Data name | Value       |
| --------- | ----------- |
| isSuccess | **Boolean** |

## 藍芽遠端關閉（伺服器端）(POST)
- 請求路線：音箱 -> 伺服器
### Request Body
| Parameters          | Value                    | 
| ------------------- | ------------------------ |
| speakerBluetoothMAC | **String: 12 character** |
### Response Body
| Data name | Value       |
| --------- | ----------- |
| isSuccess | **Boolean** |

## 藍芽遠端設定（音箱端）(POST)
- 請求路線：伺服器 -> 音箱 
### Request Body
| Parameters            | Value                                  |
| --------------------- | -------------------------------------- |
| mode                  | **String**: "open", "connect", "close" |
| connectToBluetoothMAC | **String: 12 character**               | 

*connectToBluetoothMAC is only required in connect mode.
### Response Body
| Data name | Value       | 
| --------- | ----------- |
| isSuccess | **Boolean** |

 End of dual Speaker-->
## 1.音箱後端API
### 藍牙音箱更改名稱(POST)
#### Response Body
| Data name           | Value                                                      |
| ------------------- | ---------------------------------------------------------- |
| bluetoothDeviceName | **String**  |
### 取得使用者設定之地區(GET)
- 請求路線：音箱 -> 伺服器

<!-- ### Parameters 
| Parameters |  |
| --------------- | ------------------------------------------ |
|  |  | -->

#### Response Body
| Data name     | Value                                                      |
| ------------- | ---------------------------------------------------------- |
| userArea      | **String** <br> 使用者設定之位置 <br> 全球都市 or 臺灣縣市 |

<!-- | weatherApiKey | **String**                                                 | -->

### 系統 playing 狀態偵測(Post)
- 請求路線：音箱 -> 伺服器

#### Response Body
| Data name     | Value                                                      |
| ------------- | ---------------------------------------------------------- |
| isPlaying    | **Boolean** <br> 音樂是否正在播放 <br> T為是，F為否 |
| isPause      | **Boolean** <br> 音樂是否暫停中 <br> T為是，F為否 |
| isStop      | **Boolean** <br> 音樂是否停止 <br> T為是，F為否 |

<!-- ## Youtube API(GET)
- 請求路線：音箱 -> 伺服器

### Response Body
| Data name           | Value                                         |
| ------------------- | --------------------------------------------- |
| youtubeApiKey | **String** | -->

### Google 使用者 Access_Token(Get)
- 請求路線：音箱 -> 伺服器

| Data name     | Value         |
| ------------- | ------------- |
| ACCESS_TOKEN  | **String**    |
| API_KEY       | **String**    | 
| CLIENT_SECRET | **json file** |

### 傳送搜尋結果給前端網頁(POST)
- 請求路線：音箱 -> 伺服器
#### Request Body
| Data name       | Value      |
| --------------- | ---------- |
| searchResultURL | **String**<br> 搜尋結果的網址 |
| searchKeyWord   | **String** <br> 用來搜尋的關鍵字|
|      time       | **String** <br> 用來確認搜尋結果是否超過48小時|

### 傳送搜尋結果給使用者的 LINE 帳號(POST)
- 請求路線：音箱 -> 伺服器
#### Request Body
| Data name       | Value      |
| --------------- | ---------- |
| searchResultURL | **String** |
| userLINEID      | **String** |
| searchKeyWord   | **String** <br> 用來搜尋的關鍵字|
    
### Google Calendar (Get)
- 請求路線：音箱 -> 伺服器

#### Response Body
| Data name     | Value         |
| ------------- | ------------- |
| ACCESS_TOKEN  | **String**    |
| API_KEY       | **String**    |
| CLIENT_SECRET | **json file** |

### 請求刪除音箱資料（POST）
要求伺服器清除清除該音箱資料（如果該音箱已經綁定一名使用者，要求伺服器取消綁定）

- 請求路線： 音箱 -> 伺服器

#### Request Body 
| Parameters      | Value                                        |
|:--------------- |:-------------------------------------------- |
| speakerNickname | **string** <br> 使用音箱的暱稱作為查詢的依據 |

#### Response Body
| Data name | Value       |
| --------- | ----------- |
| isSuccess | **boolean** |


### 關鍵字更新（GET）

- 不用確認版本，直接更新

<!-- route範例: https://xxx.com/api/keywords -->


#### Response Body
- 格式: Json
```json=
{
    function_name1:{
        keywords:["word1","word2","word3"]
    },
    function_name2:{
        keywords:["word1","word2","word3"]
    },
    
}
```

### LOG接收（POST）

- 要接收不同音箱的LOG

#### Response Body
| Data name | Value       |
| --------- | ----------- |
| status    | **string**  |

### 將語音備忘錄傳至LINE(POST)
#### Request Body
| Data name       | Value      |
| --------------- | ---------- |
| audio_file      |  **file**  |
| file_name       | **string** |
| timestamp       | **string** |

### 開啟 Wi-Fi AP
#### Response Body
| Data name | Value      |
| --------- | --------   |
| isSuccess | **Boolean** |

### 關閉 Wi-Fi AP
#### Response Body
| Data name | Value      |
| --------- | --------   |
| isSuccess | **Boolean** |

### 掃描 Wi-Fi
#### Response Body
| Data name | Value      |
| --------- | ---------- |
| WIFI_INFO | **json file**|
```json=
[
    {
        "SSID" : "wifi1" ,
        "Frequency" : "2.4 GHz" ,
        "Encryption" : "on" ,
        "Security" : "WPA-EAP",
        "Quality" : "72/100" ,
        "Signal" : "43/100"
    },
    {
        "SSID" : "wifi2" ,
        "Frequency" : "5 GHz" ,
        "Encryption" : "on" ,
        "Security" : "WPA2-PSK",
        "Quality" : "88/100" ,
        "Signal" : "42/100"
    }
]
```

### 連接 Wi-Fi
#### Request Body
| Data name | Value |
| --------- | --------- |
| SSID      | **string** |
| password  | **string** |
#### Response Body
| Data name | Value      |
| --------- | --------   |
| isConnected | **Boolean** |

## 2.前端網頁API

### 使用者資料(GET)
#### Request
- user_email: required
#### Response Body

| Data name    | Value       |備註           | 
| ---------    | ----------- |--------------|
| status       | **string**  |              |
| account      | **string**  | 已刪除        |
| user_name    | **string**  | 已刪除        |
| region       | **string**  | 已更新到音箱   |
| time_zone    | **string**  | 已更新到音箱   |
| music_account| **string**  |              |
| device       | **string**  | 這是一個列表，每個 element 都有 dev_id 跟 dev_name |
| user_name    | **string**  | 使用者名稱     |

### 使用者的音箱資訊(GET)
#### Request
- dev_id: required
#### Reponse

| Data name    | Value       |備註           | 
| ---------    | ----------- |--------------|
| status       | **string**  |              |
| device_id    | **string**  | 沒有這個，另外改成 dev_id     |
| account      | **string**  | 可以不用 |
| device_name  | **string**  | 改成 dev_name |
| language     | **string**  |              |
| system_volume| **int**     |              |
| media_volume | **int**     |              |
| region       | **string**  | 已更新到音箱   |
| time_zone    | **string**  | 已更新到音箱   |

### 使用者資料(GET)
#### 修改帳號
#### Request
- user_email: required
- new_email: required
#### Response
| Data name          | Value       |備註                 |
| ------------------ | ----------- |------------------- |
| old_account        | **string**  | 取消 |
| new_account        | **string**  | 取消 |
| verification_code  | **string**  | 取消 |
| status             | **string**  |              |

#### 修改名稱
#### Request
- user_email: required
- user_name: required
#### Response
| Data name      | Value       |備註           |
| ---------      | ----------- |--------------|
| status         | **string**  |              |

#### 修改地區
#### Request
- dev_id: required
- region: required
#### Response
| Data name      | Value       |備註           |
| ---------      | ----------- |--------------|
| status       | **string**  |              |
<!-- | account        | **string**        |              |
| region         | **string**        |              |
| time_zone      | **string**        |              | -->

#### 修改時區
#### Request
- dev_id: required
- time_zone: required
#### Response
| Data name      | Value       |備註           |
| ---------      | ----------- |--------------|
| status       | **string**  |              |

#### 新增裝置
#### Request
- user_token: required
- user_email: required
- language: required
- time_zone: required
- region: required
- dev_name: optional
- system_volumn: optional
- media_volumn: optional
#### Response
| Data name    | Value       |備註           |
| ---------    | ----------- |--------------|
| status       | **string**  |              |
<!-- | account      | **string**  | 指向使用者資料-account |
| device_id    | **string**  |              |
| device_name  | **string**  |              |
| language     | **string**  |              |
| system_volume| **int**     |              |
| media_volume | **int**     |              | -->


#### 刪除音箱
#### Request
- dev_id: required
#### Response
| Data name    | Value       |備註           | 
| ---------    | ----------- |--------------|
| status       | **string**  |              |
<!-- | account      | ****        |              |
| device_id    | ****        |              | -->