Device API
This API allows your service to request a user's device data and control the device.
Basic Information
Base URL
|
Server Phase |
URL | Remark |
|---|---|---|
| QA (DEV) |
https://{region}-qa-ext.lgthinq.com |
region
|
| OP |
https://{region}-ext.lgthinq.com |
API List
| Method | Summary |
|---|---|
GET /devices |
Gets a list of the user's devices. |
GET /devices/profile/{device-id} |
Gets the device's Device Profile depending on its type. |
GET /devices/{device-id} |
Gets the device Status. |
POST /devices/{device-id} |
Controls the device. |
Get User's Device List
GET /devices
Description
This method allows your service to get a list of the devices that are registered to the ThinQ Server.
Be aware that your service must have permission to get the list. For example, if your service has permission only for refrigerators, it will only get the list of devices that are in the refrigerator type, even if the user has registered multiple devices including not only a refrigerator but also a washer and dryer. The permission is determined by target device settings (allowedDevices) on your service information.
GET {Base_URL}/devices
This method must be called in first before using other methods.
The list of devices returned by this method contains a device-id that identifies a specific device. With this value, you can specify a device to call the other methods. Therefore, this method should be called at least once in the beginning. Once you've got the list, however, you do not need to call it each time.
Parameter
Header Parameters
Common Header
Body Parameters
None
Result
There are two results (Succeeded, Failed) for this method call.
Succeeded
If succeeded, the list of devices for which your service has permission is returned in the following format.
|
Name |
Type |
Description |
|
|---|---|---|---|
|
deviceId |
string |
An ID that can identify the device |
|
|
deviceInfo |
object |
An object containing the followings: |
|
|
deviceType |
enum |
Appliance type of the device (The values defined in Common Data Type > Device Type) |
|
|
modelName |
string |
A model name of the device |
|
|
alias |
string |
An alias of the device |
|
|
reportable |
boolean |
Whether or not your service is subscribing to events which occur when the device status changes |
|
|
groupId |
string |
Used when the deviceType is groupId |
|
An empty value is returned when there are no devices that the user registered to ThinQ Server.
Failed
If failed, it returns error codes and error messages defined in the Common Response.
Example of Request
[GET] {{ENDPOINT_URL}}/devices
## Header
{
" Authorization" : "Bearer 5a9a713f51a95c53d781addd1af0dfa4f6e1e7420a8bff3c5198308dac571aa9845832b8d29bbe1f04deec2d35229c6d",
" x-country-code" : "KR",
" x-message-id" : "0123456789012345678912",
" x-service-id" : "470ae4c534ba143cad86e5c3",
" x-service-key" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlSWQiOiI0NzBhZTRjNTM0YmExNDNjYWQ4NmU1YzMiLCJ0b2tlblNlZWQiOiI1Zjc2MWQwMDU2YmE4NWJkIiwidGltZSI6MTUxNjM0MTkzMn0.aznAEnUItCWc2UAFvoiIYDw0SCJDoY5xVCNnUyUJeiI"
}
Example of Response
{
" messageId" : " 0123456789012345678912" ,
" timestamp" : " 2018-02-08T06:23:20.866279" ,
" response" : [{
"deviceId": "0A36FC52-6281-4954-86D5-616A58CEA2C6",
"deviceInfo": {
"deviceType": "DEVICE_REFRIGERATOR",
"modelName": "S-TF",
"alias": "nickname",
"reportable": true
}
}]
}
Get Device Profile
GET /devices/profile/{device-id}
Description
This method allows your service to get the Device Profile.
Device profile in ThinQ Server is the standardized data describing LG Home appliances by its type. For example, the Device Profile of a refrigerator includes properties such as temperature, freezing mode, power saving mode, door opening, etc. which are used to control the refrigerator or describe its status. Based on such profile, you can monitor the device's status and deliver control commands.
GET {Base_URL}/devices/profile/{device-id}
If this method is successfully called, it returns the Device Profile in JSON format depending on the appliance type of the device specified as device-id.
Precondition
When calling the API to get the device-id value for a certain device, you should call GET /devices at least once before using this method.
Parameter
Header Parameters
Common Header
Body Parameters
None
Result
There are two results (Succeeded, Failed) for this method call.
Succeeded
If succeeded, the Device Profile is returned in JSON format depending on the type of device. Refer to the following table for the meaning of each property in the Device Profile.
|
Device Type |
Device Profile |
|---|---|
|
Refrigerator |
|
|
Washer |
|
|
Dryer |
|
|
Air Conditioner |
|
|
Air Purifier |
|
|
Robot Cleaner |
|
|
Oven |
|
|
Dish Washer |
|
|
Styler |
|
|
Water Purifier |
|
|
Dehumidifier |
|
|
Ceiling Fan |
Failed
If failed, it returns error codes and error messages defined in the Common Response.
Example of Request
[GET] {{ENDPOINT_URL}}/devices/profile/{device-id}
## Header
{
" authorization" : "Bearer a6586272fc390566850bc5a837d32872f0c794498f651b5174244451700e2ea00ddb8dcc96902ea469aa765e589a221d",
" x-country-code" : "KR",
" x-message-id" : "0123456789012345678912",
" x-service-id" : "470ae4c534ba143cad86e5c3",
" x-service-key" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlSWQiOiI0NzBhZTRjNTM0YmExNDNjYWQ4NmU1YzMiLCJ0b2tlblNlZWQiOiI1Zjc2MWQwMDU2YmE4NWJkIiwidGltZSI6MTUxNjM0MTkzMn0.aznAEnUItCWc2UAFvoiIYDw0SCJDoY5xVCNnUyUJeiI"
}
Example of Response
{
" messageId" : " c2d362a0-dd0f-11e6-a7c7-abfb76e3e664" ,
" timestamp" : " 1284101485" ,
" response" : {{ Device Profile }}
}
Get Device Status
GET /devices/{device-id}
Description
This method allows your service to get the device's status.
GET {Base_URL}/devices/{device-id}
If this method is successfully called, it returns current status data of the device specified as device-id.
Precondition
When calling the API to get the device-id value for a certain device, you should call GET /devices at least once before using this method.
Parameter
Header Parameters
Common Header
Body Parameters
None
Result
There are two results (Succeeded, Failed) for this method call.
Succeeded
If succeeded, it returns the current status of the device. The value is returned in JSON format created based on the device profile. Refer to the following table to check the meaning of the data since the data structure differs for each type of home appliance.
|
Device Type |
Status Inquiry Result |
|---|---|
|
Refrigerator |
|
|
Washer |
|
|
Dryer |
|
|
Air Conditioner |
|
|
Air Purifier |
|
|
Robot Cleaner |
|
|
Oven |
|
|
Dish Washer |
|
|
Styler |
|
|
Water Purifier |
|
|
Dehumidifier |
|
|
Ceiling Fan |
Failed
If failed, it returns error codes and error messages defined in the Common Response.
Example of Request
[GET] {{ENDPOINT_URL}}/devices/{device-id}
## Header
{
" Authorization" : "Bearer 13d6800857e953e58c0a9f0cf4c1c298ecfa3012d1f9486a1925397a1f2a5d13ac6c898c9eaabda9c57ee8e8eca1006a",
" x-country-code" : "KR",
" x-message-id" : "0123456789012345678912",
" x-service-id" : "470ae4c534ba143cad86e5c3",
" x-service-key" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlSWQiOiI0NzBhZTRjNTM0YmExNDNjYWQ4NmU1YzMiLCJ0b2tlblNlZWQiOiI1Zjc2MWQwMDU2YmE4NWJkIiwidGltZSI6MTUxNjM0MTkzMn0.aznAEnUItCWc2UAFvoiIYDw0SCJDoY5xVCNnUyUJeiI"
}
Example of Response
{
" messageId" : " c2d362a0-dd0f-11e6-a7c7-abfb76e3e664" ,
" timestamp" : " 1284101485" ,
" response" : {{ Device Status }}
}
Control Device
POST /devices/{device-id}
Description
This method allows your service to control the device.
POST {Base_URL}/devices/{device-id}
If this method is successfully called, it delivers your control command to the device specified as device-id. The control command is the data expressed as a name-value pair for the properties that you want to control and it is defined in the Device Profile. It is sent to the body parameter of this method.
Precondition
When calling the API to get the device-id value for a certain device, you should call GET /devices at least once before using this method.
Parameter
Header Parameters
Common Header
If x-conditional-control in the header is true, the request first retrieves the device status and executes the control command only in a controllable status.
Body Parameters
Enter the control command for the device. Control command is the data expressed as a name-value pair for the properties that you want to control based on the Device Profile.
|
Name |
Type |
Required |
Description |
|---|---|---|---|
|
name |
string |
mandatory |
Resource name in the Device Profile |
|
value |
string |
mandatory |
Resource value in the Device Profile |
For example, the command to control the refrigeration room temperature to Celsius 0 degree is as follows:
# example of the refrigeration room Celsius 0 degree control command
{
"temperature": {
"targetTemperature": 0,
"locationName": "FRIDGE",
"unit": "C"
}
}
Refer to the following example for the control command which can be used for each type of home appliance.
|
Device Type |
Example |
|---|---|
|
Refrigerator |
|
|
Washer |
|
|
Dryer |
|
|
Air Conditioner |
|
|
Air Purifier |
|
|
Robot Cleaner |
|
|
Oven |
|
|
Dish Washer |
N/A |
|
Styler |
|
|
Water Purifier |
N/A |
Result
There are two results (Succeeded, Failed) for this method call.
Succeeded
If succeeded, the device status data after performing the control command is returned. The value is returned in JSON format created based on the Device Profile. Refer to the following table to check the meaning of the data since its structure differs for each type of home appliance.
If succeeded, it returns HTTP 200 OK response Code.
Failed
If failed, it returns error codes and error messages defined in the Common Response.
Example of Request
[POST] {{ENDPOINT_URL}}/device/{device-id}
## Header
{
" Authorization" : "Bearer 13d6800857e953e58c0a9f0cf4c1c298ecfa3012d1f9486a1925397a1f2a5d13ac6c898c9eaabda9c57ee8e8eca1006a",
" x-country-code" : "KR",
" x-message-id" : "0123456789012345678912",
" x-service-id" : "470ae4c534ba143cad86e5c3",
" x-service-key" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlSWQiOiI0NzBhZTRjNTM0YmExNDNjYWQ4NmU1YzMiLCJ0b2tlblNlZWQiOiI1Zjc2MWQwMDU2YmE4NWJkIiwidGltZSI6MTUxNjM0MTkzMn0.aznAEnUItCWc2UAFvoiIYDw0SCJDoY5xVCNnUyUJeiI",
" content-type" : "application/json"
}
## Body
{
" temperature" : {
" targetTemperature" : 0 ,
" locationName" : " FRIDGE" ,
" unit" : " C"
}
}
Example of Response
{
" messageId" : " c2d362a0-dd0f-11e6-a7c7-abfb76e3e664" ,
" timestamp" : " 1284101485" ,
" response" : {}
}