IOTOWN Manual

Home Open API Reference
1. Introduction 2. API List 3. Error Description
4. API Descriptions
[GET] gateways [GET] gateway/{gateway_id} [POST] gateway [PUT] gateway/{gateway_id} [DELETE] gateway [GET] gateway/{gateway_id}/connected-nodes [GET] gateway/{gateway_id}/stats [GET] nodes [GET] node/{node_id} [POST] node [DELETE] node [POST] storage/search [GET] storage [PUT] callback [GET] callback [DELETE] callback [GET] command [POST] command [DELETE] command [POST] data [DELETE] data

1. Introduction

IOTOWN은 타 시스템에서 연동하기 위하여 RESTful API를 제공합니다.
API를 사용하려면 토큰이 필요하며 IOTOWN에 로그인 후 Open API 토큰 메뉴에서 얻을 수 있습니다.

Admin계정의 토큰을 사용하면 API를 사용할 때 모든 그룹에 대한 접근이 가능합니다. Admin계정으로 로그인하면 Open API 토큰 메뉴에서 토큰을 얻을 수 있습니다.
Admin토큰을 사용하려면 API호출시 header에 접근하고자 하는 그룹의 ID(grpid)를 넣어야 합니다.

key value
Content-Type application/json
Accept application/json
Token {your_own_token}
grpid (Admin token only) {group_id_to_access}

2. API List

3. Error Descriptions

HTTP request에 대한 response code가 200인 경우 성공을 의미합니다. 반면, 200이 아닌 경우 오류로 인해 정상 처리되지 않았음을 의미합니다. Status code와 더불어 모든 response는 JSON 포맷의 payload가 반환되며, 여기에는 errorCode와 errorMsg을 반환합니다. Status code에 대한 설명은 아래 정리되어 있습니다. 자세한 설명은 errorMsg를 참고하시기 바랍니다.

{
  "errorCode": 200,
  "errorMsg": "OK"
}
errorCode는 HTTP response code와 동일한 값입니다.
Response code Description
200 성공
400 Bad Request
401 Invalid Token
500 서버에 문제가 발생했거나 처리가 불가능한 요청인 경우
(주의사항) 시간 표기법
API에서 리턴되는 모든 시간 정보는 표준 UTC시간이므로 원하는 시간대에 맞게 변형해서 사용해야 합니다.

4. API Descriptions

[GET] gateways

URL : https://town.coxlab.kr/api/v1.0/gateways

이 API를 통해서 IOTOWN과 연동된 게이트웨이 목록을 가져올 수 있습니다.

Header

  • Token: API 토큰

Response

  • gateways[]: 게이트웨이 객체 배열
  • gateway_id: 게이트웨이 아이디
  • gateway_eui: 게이트웨이 EUI
  • gateway_type: IOTOWN 등록시 사용자가 임의 입력하는 정보
  • gateway_desc: IOTOWN 등록시 사용자가 임의 입력하는 정보
  • created_at: IOTOWN에 등록된 시간(UTC)
  • recent_act (optional): 게이트웨이가 마지막으로 동작한 시간(UTC)
  • bootup_time (optional): 마지막으로 부팅된 시간(UTC). 부팅 메세지가 누락된 경우, 필드가 없을 수 있음.
  • latitude (optional): 위도
  • longitude (optional): 경도
  • altitude (optional): 고도
  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X GET --header 'Accept: application/json' --header 'Token: your_own_token' 'https://town.coxlab.kr/api/v1.0/gateways'
Invoke-WebRequest
Invoke-WebRequest -Method 'GET' -Headers @{'Accept'='application/json';'Token'='your_own_token'} -Uri https://town.coxlab.kr/api/v1.0/gateways
Return
{
  "gateways":[
    {
      "created_at":"2016-05-30T05:54:59.995Z",
      "gateway_id":"GW002",
        ...
    },
    {
      "created_at":"2016-05-30T05:27:14.808Z",
      "gateway_id":"GW001",
        ...
    }
    ...
  ],
  "errorCode":200,
  "errorMsg":"Success"
}

[GET] gateway/{gateway_id}

URL : https://town.coxlab.kr/api/v1.0/gateway/{gateway_id}

이 API를 통해서 IOTOWN과 연동된 특정 게이트웨이의 정보를 가져올 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • gateway_id: 게이트웨이 아이디

Response

  • gateway: 게이트웨이 객체
  • gateway_id: 게이트웨이 아이디
  • gateway_eui: 게이트웨이 EUI
  • gateway_type: IOTOWN 등록시 사용자가 임의 입력하는 정보
  • gateway_desc: IOTOWN 등록시 사용자가 임의 입력하는 정보
  • created_at: IOTOWN에 등록된 시간(UTC)
  • recent_act (optional): 게이트웨이가 마지막으로 동작한 시간(UTC)
  • bootup_time (optional): 마지막으로 부팅된 시간(UTC). 부팅 메세지가 누락된 경우, 필드가 없을 수 있음.
  • latitude (optional): 위도. 만약 Gateway Management 페이지에서 별도로 설정한 좌표 정보가 있거나 게이트웨이로부터 실시간 위치 정보가 제공되는 경우에만 이 필드가 존재합니다.
  • longitude (optional): 경도. 만약 Gateway Management 페이지에서 별도로 설정한 좌표 정보가 있거나 게이트웨이로부터 실시간 위치 정보가 제공되는 경우에만 이 필드가 존재합니다.
  • altitude (optional): 고도. 만약 Gateway Management 페이지에서 별도로 설정한 좌표 정보가 있거나 게이트웨이로부터 실시간 위치 정보가 제공되는 경우에만 이 필드가 존재합니다.
  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X GET --header 'Accept: application/json' --header 'Token: your_own_token' 'https://town.coxlab.kr/api/v1.0/gateway/GW001'
Invoke-WebRequest
Invoke-WebRequest Method 'GET' -Headers @{'Accept'='application/json';'Token'='your_own_token'} -Uri https://town.coxlab.kr/api/v1.0/gateway/GW001
Return
{
  "gateway":{
    "bootup_time":"2016-06-01T07:03:21.445Z",
    "created_at":"2016-05-30T05:27:14.808Z",
    "gateway_desc":"GW001설명",
    "gateway_id":"GW001"
    "gateway_type":"GW001종류",
    "gateway_eui":"AA555A0000000101",
    "recent_act":"2016-06-04T02:11:16.902Z",
    "latitude":"36.49197",
    "longitude":"127.25633",
    "altitude":"10.5"
  },
  "errorCode":200,
  "errorMsg":"Success"
}

[POST] gateway

URL : https://town.coxlab.kr/api/v1.0/gateway

이 API를 통해서 IOTOWN에 게이트웨이를 등록할 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • gid: 게이트웨이 아이디
  • eui: 게이트웨이 EUI
  • type: 게이트웨이 타입
  • desc: 게이트웨이 설명
  • lora: LoRaWAN Band 이름 (예: KR920, K920_FSK, AS923 등)

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Token: your_own_token' -d '{"gid":"G001","eui":"1111222233334444","type":"gateway type","desc":"gateway desc","lora":"KR920"}' 'https://town.coxlab.kr/api/v1.0/gateway'
Invoke-WebRequest
Invoke-WebRequest -Method 'POST' -Headers @{'Content-Type'='application/json'; 'Accept'='application/json'; 'Token'='your_own_token'} -Body '{"gid":"G001","eui":"1111222233334444","type":"gateway type","desc":"gateway desc","lora":"KR920"}' -Uri https://town.coxlab.kr/api/v1.0/gateway
Return
{
  "errorCode":200,
  "errorMsg":"Success"
}

[PUT] gateway/{gateway_id}

URL : https://town.coxlab.kr/api/v1.0/gateway/{gateway_id}

이 API를 통해서 게이트웨이의 정보를 수정할 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • type (optional): 게이트웨이 타입
  • desc (optional): 게이트웨이 설명
  • group_id (optional, Admin token only): 그룹 아이디

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Token: your_own_token' -d '{"type":"gateway type","desc":"gateway desc"}' 'https://town.coxlab.kr/api/v1.0/gateway/G001'
Invoke-WebRequest
Invoke-WebRequest -Method 'POST' -Headers @{'Content-Type'='application/json'; 'Accept'='application/json'; 'Token'='your_own_token'} -Body '{"type":"gateway type","desc":"gateway desc"}' -Uri https://town.coxlab.kr/api/v1.0/gateway/G001
Return
{
"errorCode":200,
"errorMsg":"Success"
}

[DELETE] gateway

URL : https://town.coxlab.kr/api/v1.0/gateway

이 API를 통해서 IOTOWN에 등록된 게이트웨이를 삭제할 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • gid: 게이트웨이 아이디

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Token: your_own_token' -d '{"gid":"G001"}' 'https://town.coxlab.kr/api/v1.0/gateway'
Invoke-WebRequest
Invoke-WebRequest -Method 'DELETE' -Headers @{'Content-Type'='application/json'; 'Accept'='application/json'; 'Token'='your_own_token'} -Body '{"gid":"G001"}' 'https://town.coxlab.kr/api/v1.0/gateway'
Return
{
  "errorCode":200,
  "errorMsg":"Success"
}

[GET] gateway/{gateway_id}/connected-nodes

URL : https://town.coxlab.kr/api/v1.0/gateway/{gateway_id}/connected-nodes

이 API를 통해서 IOTOWN과 연동된 특정 게이트웨이의 하위 장치 목록을 가져올 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • gateway_id: 게이트웨이 아이디

Response

  • nodes[]: 게이트웨이에 연결된 장치 리스트 객체
  • node_id: 장치 아이디
  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X GET --header 'Accept: application/json' --header 'Token: your_own_token' 'https://town.coxlab.kr/api/v1.0/gateway/G001/connected-nodes'
Invoke-WebRequest
Invoke-WebRequest -Method 'GET' -Header @{'Accept'='application/json'; 'Token'='your_own_token'} -Uri 'https://town.coxlab.kr/api/v1.0/gateway/G001/connected-nodes'
Return
{
  "nodes" : [
    {"node_id" : "N001"},
    {"node_id" : "N002"},
    ...
  ],
  "errorCode":200,
  "errorMsg":"Success"
}

[GET] gateway/{gateway_id}/stats

URL : https://town.coxlab.kr/api/v1.0/gateway/{gateway_id}/stats

이 API를 통해서 IOTOWN과 연동된 특정 게이트웨이의 통계 정보를 가져올 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • gateway_id: 게이트웨이 아이디
  • interval: 정보의 표시 시간 단위 (hour / day)
  • from: 검색 시간 범위(시작시간)
  • to: 검색 시간 범위(끝시간)

Response

  • stats[]: 통계 정보
  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X GET --header 'Accept: application/json' --header 'Token: your_own_token' 'https://town.coxlab.kr/api/v1.0/gateway/G001/stats'
Invoke-WebRequest
Invoke-WebRequest -Method 'GET' -Headers @{'Accept'='application/json'; 'Token'='your_own_token'} -Uri 'https://town.coxlab.kr/api/v1.0/gateway/G001/stats'
Return
{
  "stats" : [
    {
      "timestamp": "2019-01-01T12:00:00Z",
        "rxPacketsReceived": 103,
        "rxPacketsReceivedOK": 23,
        "txPacketsReceived": 0,
        "txPacketsEmitted": 0
    }
    ...
  ],
  "errorCode":200,
  "errorMsg":"Success"
}

[GET] nodes

URL : https://town.coxlab.kr/api/v1.0/nodes

이 API를 통해서 IOTOWN에 등록된 장치 목록을 가져올 수 있습니다.

Header

  • Token: API 토큰

Response

  • nodes[]: 장치 객체 배열
  • node_id: 장치 아이디
  • node_type: IOTOWN 등록시 사용자가 임의 입력하는 정보
  • node_desc: IOTOWN 등록시 사용자가 임의 입력하는 정보
  • created_at: IOTOWN에 등록된 시간(UTC)
  • connected_gw_id (optional): 장치가 연결된 게이트웨이 아이디. 부팅 메세지가 누락된 경우 제외
  • bootup_time (optional): 마지막으로 부팅된 시간(UTC). 부팅 메세지가 누락된 경우 제외
  • last_data (optional): 마지막에 기록된 데이터 객체. 데이터가 한번도 기록되지 않은 경우 제외
  • last_timestamp (optional): 마지막 데이터가 기록된 시간(UTC). 데이터가 한번도 기록되지 않은 경우 제외
  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X GET\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  'https://town.coxlab.kr/api/v1.0/nodes'
Return
{
  "nodes" : [
    {
      "node_id":"N001",
      "node_type":"N001종류",
      "node_desc":"N001설명",
      "created_at":"2016-05-27T08:13:31.633Z"
    },
    {
      "node_id":"N002",
      "node_type":"N002종류",
      "node_desc":"N002설령",
      "bootup_time":"2016-05-26T08:07:05.893Z",
      "connected_gw_id":"GW001",
      "created_at":"2016-05-27T08:13:31.633Z",
      "last_data":{"CC":"33","BB":"11","AA":"00"},
      "last_timestamp":"2016-05-30T07:50:10.848Z"
    },
    ...
    }
  ],
  "errorCode":200,
  "errorMsg":"Success"
}

[GET] node/{node_id}

URL : https://town.coxlab.kr/api/v1.0/node/{node_id}

이 API를 통해서 IOTOWN에 등록된 장치 정보를 가져올 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • node_id: 장치 아이디

Response

  • node: 장치 객체
  • node_id: 장치 아이디
  • node_type: IOTOWN 등록시 사용자가 임의 입력하는 정보
  • node_desc: IOTOWN 등록시 사용자가 임의 입력하는 정보
  • created_at: IOTOWN에 등록된 시간(UTC)
  • connected_gw_id (optional): 장치가 연결된 게이트웨이 아이디. 부팅 메세지가 누락된 경우 제외
  • bootup_time (optional): 마지막으로 부팅된 시간(UTC). 부팅 메세지가 누락된 경우 제외
  • last_data (optional): 마지막에 기록된 데이터 객체. 데이터가 한번도 기록되지 않은 경우 제외
  • last_timestamp (optional): 마지막 데이터가 기록된 시간(UTC). 데이터가 한번도 기록되지 않은 경우 제외
  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X GET\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  'https://town.coxlab.kr/api/v1.0/node/N001'
Return
{
  "node": {
    "node_id":"N001",
    "node_type":"N001종류",
    "node_desc":"N001설명",
    "created_at":"2016-05-27T08:13:31.633Z",
    "last_data":{
      "A":"0",
      "B":"1"
    },
    "last_timestamp":"2016-05-30T07:50:52.033Z"
  },
  "errorCode":200,
  "errorMsg":"Success"
}

[POST] node

URL : https://town.coxlab.kr/api/v1.0/node

이 API를 통해서 IOTOWN에 장치를 등록할 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • nid: 장치 아이디
  • type(optional): 장치 타입
  • desc(optional): 장치 설명
  • profile(optional) : LoRa Device Profile 이름 (deprecated)
  • lorawan(optional) : Object 형태로 LoRa Device Profile과 App key를 지정할 수 있습니다. LoRa용 장치인 경우 필수이며 IOTOWN의 장치 등록에서 Device Profile 목록을 확인 가능합니다. (2019/1/10 이후 버전부터 가능)

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X POST\
  --header 'Content-Type: application/json'\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  -d '{\
    "nid":"LW1111222233334444",\
    "type":"node type",\
    "desc":"node desc",\
    "lorawan": {\
      "profile" : "KR920 1.0.2 A",\
      "appKey" : "11112222333344445555666677778888"\
    }\
  }'\
  'https://town.coxlab.kr/api/v1.0/node'
Return
{
  "errorCode":200,
  "errorMsg":"Success"
}

[DELETE] node

URL : https://town.coxlab.kr/api/v1.0/node

이 API를 통해서 IOTOWN에 등록된 장치를 삭제할 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • nid: 장치 아이디

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X DELETE\
  --header 'Content-Type: application/json'\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  -d '{\
    "nid":"LW1111222233334444"\
  }'\
  'https://town.coxlab.kr/api/v1.0/node'
Return
{
  "errorCode":200,
  "errorMsg":"Success"
}

[POST] storage/search (deprecated)

URL : https://town.coxlab.kr/api/v1.0/storage/search

이 API를 통해서 IOTOWN에 저장된 데이터를 가져올 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • nid (optional): 장치 아이디. 콤마(,)로 구분. (예 : nid:"N001,N002,N003") nid가 없을 경우 모든 장치를 대상으로 검색
  • from (optional): 검색할 시간 범위의 시작값 UTC형태만 가능. (예: from:2016-06-01T13:45+09:00)
  • to (optional): 검색할 시간 범위의 끝값. UTC형태만 가능. (예: to:2016-06-25T13:45+09:00)
  • lastKey (optional): 검색 결과가 5000개를 초과할 경우, 5000개와 함께 lastKey가 리턴됨. 동일 검색 조건에 lastKey를 추가하여 다시 호출하면 다음 5000개를 리턴함.(반복적으로 5000개씩 로딩 가능)

Response

  • data: 검색된 데이터 객체 배열
  • node_id: 장치 아이디
  • name: 데이터 이름
  • value: 데이터 값
  • timestamp: 데이터가 기록된 시간(UTC)
  • lastKey (optional): 검색 결과가 5000개를 초과할 경우, 5000개와 함께 lastKey가 리턴됨. 동일 검색 조건에 lastKey를 추가하여 다시 호출하면 다음 5000개를 리턴함.(반복적으로 5000개씩 로딩 가능)
  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X POST\
  --header 'Content-Type: application/json'\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  -d '{\
    "nid" : "N001",\
    "from" : "2016-02-01T13:45+09:00",\
    "to" : "2016-05-30T13:55+09:00"\
  }'\
  'https://town.coxlab.kr/api/v1.0/storage/search'
Return
{
  "data":[
    {
      "node_id":"N001",
      "name":"B",
      "value":"1",
      "timestamp":"2016-02-30T07:50:52.033Z"
    },
    ...
    {
      "node_id":"N001",
      "name":"B",
      "value":"1",
      "timestamp":"2016-05-30T09:50:21.748Z"
    }
  ],
  "lastKey":"574bf0dbabe178ec1f776758",
  "errorCode":200,
  "errorMsg":"Success"
}

위의 예제처럼 lastKey가 리턴된 경우, 아래와 같이 lastKey를 포함하여 아래와 같이 다시 호출하면 다음 5000개를 불러옴.

{
  "nid" : "001",
  "from" : "2016-02-01T13:45+09:00",
  "to" : "2016-05-30T13:55+09:00",
  "lastKey" : "574bf0dbabe178ec1f776758"
}
URL : https://town.coxlab.kr/api/v1.0/storage

이 API를 통해서 IOTOWN에 저장된 데이터를 가져올 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • nid (optional): 장치 아이디. 콤마(,)로 구분. (예 : "nid=N001,N002,N003") nid가 없을 경우 모든 장치를 대상으로 검색
  • from (optional): 검색할 시간 범위의 시작값 UTC형태만 가능. (예: from:2018-11-01T13:00:00Z)
  • to (optional): 검색할 시간 범위의 끝값. UTC형태만 가능. (예: to:2018-11-02T13:00:00Z)
  • lastKey (optional): 검색 결과가 5000개를 초과할 경우, 5000개와 함께 lastKey가 리턴됨. 동일 검색 조건에 lastKey를 추가하여 다시 호출하면 다음 5000개를 리턴함.(반복적으로 5000개씩 로딩 가능)
  • count (optional): 한번에 검색되는 결과의 수를 지정 가능. (2022-01-05 이후 버전부터 지원)

Response

  • _id: 데이터를 삭제할 때 사용되는 ID값 (참조)
  • data: 검색된 데이터 객체 배열
  • node_id: 장치 아이디
  • name: 데이터 이름
  • value: 데이터 값
  • timestamp: 데이터가 기록된 시간(UTC)
  • lastKey (optional): 검색 결과가 5000개를 초과할 경우, 5000개와 함께 lastKey가 리턴됨. 동일 검색 조건에 lastKey를 추가하여 다시 호출하면 다음 5000개를 리턴함.(반복적으로 5000개씩 로딩 가능)
  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X GET\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  'https://town.coxlab.kr/api/v1.0/storage?nid=N001&from=2018-11-01T13:00:00Z&to=2018-11-02T13:00:00Z'
Return
{
  "data":[
    {
      ...
      "_id":"64d9c56ec772dd00156d5cf1"
      "node_id":"N001",
      "value": { a : "1" },
      "timestamp":"2018-11-01T07:50:52.033Z"
      ...
    },
    ...
    {
      ...
      "_id":"574bf0dbabe178ec1f776758"
      "node_id":"N001",
      "value": { a : "2" },
      "timestamp":"2018-11-01T09:50:21.748Z"
      ...
    }
  ],
  "lastKey":"574bf0dbabe178ec1f776758",
  "errorCode":200,
  "errorMsg":"Success"
}

위의 예제처럼 lastKey가 리턴된 경우, 아래와 같이 URL에 lastKey를 포함하여 다시 호출하면 다음 5000개를 불러옵니다.

curl -X GET\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  'https://town.coxlab.kr/api/v1.0/storage?nid=N001&from=2018-11-01T13:00:00Z&to=2018-11-02T13:00:00Z&lastKey=574bf0dbabe178ec1f776758'

[PUT] callback

URL : https://town.coxlab.kr/api/v1.0/callback

이 API를 통해서 IOTOWN으로 데이터가 들어올 때마다 특정 URL로 POST 하도록 설정할 수 있습니다. 자세한 내용은 How to use callback을 참고하시기 바랍니다.
(Admin계정의 토큰 사용 불가능)

Header

  • Token: API 토큰

Parameters

  • url: callback URL

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X PUT\
  --header 'Content-Type: application/json'\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  -d '{\
    "url": "http://your.server.url"\
  }'\
  'https://town.coxlab.kr/api/v1.0/callback'
Return
{
  "errorCode":200,
  "errorMsg":"Success"
}

[GET] callback

URL : https://town.coxlab.kr/api/v1.0/callback

이 API를 통해서 [PUT] callback으로 지정한 콜백 URL을 확인할 수 있습니다.
(Admin계정의 토큰 사용 불가능)

Header

  • Token: API 토큰

Response

  • callbackUrl: 등록된 URL
  • callbackStatus: URL의 상태 코드
    • 0: 등록된 URL이 없음
    • 1: 등록된 URL이 있음
    • -1: 콜백 호출이 실패함
  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X GET\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  'https://town.coxlab.kr/api/v1.0/callback'
Return
{
  "callbackUrl":"http://your.server.url",
  "callbackStatus":"1",
  "errorCode":200,
  "errorMsg":"Success"
}

[DELETE] callback

URL : https://town.coxlab.kr/api/v1.0/callback

이 API를 통해서 [PUT] callback으로 지정한 콜백 URL을 삭제할 수 있습니다.
(Admin계정의 토큰 사용 불가능)

Header

  • Token: API 토큰

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X DELETE\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  'https://town.coxlab.kr/api/v1.0/callback'
Return
{
  "errorCode":200,
  "errorMsg":"Success"
}

주의: 리턴된 command 리스트 내의 data는 base64 decoding하여 사용해야 합니다.

[GET] command

URL : https://town.coxlab.kr/api/v1.0/command/{node_id}

이 API를 통해서 장치의 커맨드 Queue를 확인할 수 있습니다.

주의 : LoRaWAN 타입의 장치에만 사용 가능합니다.

Header

  • Token: API 토큰

Parameters

  • node_id: 장치 아이디

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용
  • command (LoRaWAN only): downlink queue 상태
    • fCnt: 전송할 메시지의 FCnt
    • fPort: 전송할 메시지의 FPort
    • data: 전송할 메시지의 payload (base64 encoded)
    • data: 전송할 메시지의 confirmed 여부

Example

cURL
curl -X POST\
--header 'Content-Type: application/json'\
--header 'Accept: application/json'\
--header 'Token: your_own_token'\
'https://town.coxlab.kr/api/v1.0/command/LW1111222233334444'
Return
{
  "errorCode":200,
  "errorMsg":"Success",
  "command":[{"fCnt":11,"fPort":67,"data":"AxMA","confirmed":true}]
}

[POST] command

URL : https://town.coxlab.kr/api/v1.0/command

이 API를 통해서 HTTP를 지원하는 IoT 장치로 명령을 전송할 수 있습니다.

주의 : LoRaWAN 타입의 장치에만 사용 가능합니다.

Header

  • Token: API 토큰

Parameters

  • nid: 장치 ID
  • type: 명령 종류 ("hex" or "string")
  • command: 명령 내용
  • lorawan (LoRaWAN only): LoRaWAN 관련 설정
    • f_port (2020/03/30 이후 버전에서만 지원): Downlink 전송시 사용할 fPort 설정. 생략시 1로 전송. 허용 가능한 범위는 1~222. 범위 밖의 값 입력시 400 반환.

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용
  • fCnt (LoRaWAN only): 전송된 downlink 프레임의 fCnt 값 (callback을 통해 fCnt가 포함된 Ack를 수신할 수 있음)

Example

cURL

type이 "string"인 경우,

curl -X POST\
  --header 'Content-Type: application/json'\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  -d '{\
    "nid":"LW1111222233334444",\
    "type":"string",\
    "command":"command_string_here"\
  }'\
  'https://town.coxlab.kr/api/v1.0/command'

type이 "hex"인 경우,

curl -X POST\
  --header 'Content-Type: application/json'\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  -d '{\
    "nid":"LW1111222233334444",\
    "type":"hex",\
    "command":"FF1234"\
  }'\
  'https://town.coxlab.kr/api/v1.0/command'
Return
{
    "errorCode":200,
    "errorMsg":"Success"
  }

[DELETE] command

URL : https://town.coxlab.kr/api/v1.0/command

이 API를 통해서 LoRa서버에 쌓여있는 command queue를 비울 수 있습니다.

주의 : LoRaWAN 장치에만 사용 가능합니다.

Header

  • Token: API 토큰

Parameters

  • nid: 장치 아이디

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X DELETE\
  --header 'Content-Type: application/json'\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  -d '{\
    "nid":"LW1111222233334444",\
  }'\
  'https://town.coxlab.kr/api/v1.0/command'
Return
{
  "errorCode":200,
  "errorMsg":"Success"
}

[POST] data

URL : https://town.coxlab.kr/api/v1.0/data

이 API를 통해서 HTTP를 지원하는 IoT 장치에서 IOTOWN으로 데이터를 전송할 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • type: 메시지 형식 (문자열 “2”로 고정)
  • nid: 장치 아이디
  • data: 전송할 데이터 내용 (JSON object)

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X POST\
  --header 'Content-Type: application/json'\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  -d '{\
    "type" : "2",\
    "nid" : "N001",\
    "data" : {\
      "temperature":26.1,\
      "humidity":43\
    }\
  }'\
  'https://town.coxlab.kr/api/v1.0/data'
Return
{
  "errorCode":200,
  "errorMsg":"Success"
}

[DELETE] data

URL : https://town.coxlab.kr/api/v1.0/data

이 API를 통해서 IOTOWN에 저장된 데이터를 삭제할 수 있습니다.

Header

  • Token: API 토큰

Parameters

  • _id: 삭제할 데이터의 ID값 (GET storage API로 읽은 데이터의 _id값을 사용, 참조)
  • nid: 삭제할 데이터의 장치 아이디
  • from (optional): 삭제할 데이터의 시간 범위 시작값. UTC형태만 가능. (예: 2023-11-02T13:00:00Z)
  • to (optional): 삭제할 데이터의 시간 범위 끝값. UTC형태만 가능. (예: 2023-11-02T13:00:00Z)

주의: _id 혹은 nid 중 1개는 필수로 포함해야 합니다.
_id는 특정 데이터를 지우기 위해 사용됩니다. nid는 특정 장치의 복수 데이터를 삭제할 수 있고, 시간조건(from, to)과 함께 사용할 수 있습니다.
_id와 nid를 같이 사용하면 _id만 적용됩니다.

Response

  • errorCode: 에러 코드
  • errorMsg: 에러 내용

Example

cURL
curl -X DELETE\
  --header 'Content-Type: application/json'\
  --header 'Accept: application/json'\
  --header 'Token: your_own_token'\
  -d '{\
    "_id":"64d9c56ec772dd00156d5cf1",\
  }'\
  'https://town.coxlab.kr/api/v1.0/data'
curl -X DELETE\
    --header 'Content-Type: application/json'\
    --header 'Accept: application/json'\
    --header 'Token: your_own_token'\
    -d '{\
      "nid":"LW1111222233334444",\
      "from":"2023-08-14T05:59:12.317Z",\
      "to":"2023-08-14T06:59:12.317Z",\
    }'\
    'https://town.coxlab.kr/api/v1.0/data'
Return
{
  "errorCode":200,
  "errorMsg":"Success"
}