Web API

はじめに

Web APIの共通仕様について説明します。

APIエンドポイント

https://api.agri.iij.jp/v1

HTTPヘッダ項目

Key	Value	Description
Authorization	Bearer {api_token}	・POST /auth以外のパスで必須・api_tokenの発行方法はPOST /authを参照
Content-Type	application/json	・固定

APIパス一覧

Path	Operation	Description
/auth	POST	api_tokenの発行
/sensors	GET	センサーの一覧取得
/sensors/{sensor_id}	GET	指定センサーの個別情報と過去のセンサーデータ取得
/sensors/{sensor_id}	PUT	指定センサーの個別設定更新

注意事項

本ドキュメントに記載がない項目は、システム上で自動的に付加された項目です。項目の使用は非推奨となります。
sensor_id, hw_addr, deveuiの英字は大文字小文字の区別はありません。内部的に全て小文字で処理されます。
Kiwi technology社製GW配下のセンサとKerlink社製GW配下のセンサで、レスポンスフォーマットが異なるAPIパスがあります。

API詳細仕様

POST /auth

Authorizationヘッダに付与するapi_tokenを発行します。

api_tokenの有効期限は90日です。有効期限が切れた場合、本APIで新しいapi_tokenを発行してください。
新たなapi_keyの発行についてはお問い合わせください。

Name	Description	Type	Data type	Memo
api_key	IIJより指定されたapi_key	body	string	required
api_secret	IIJより指定されたapi_secret	body	string	required

Responses

Status Code: 200

Name	Description	Data type
api_key	リクエストされたapi_key	string
api_token	Authorizationに付与するapi_secret	string
expired	api_tokenの有効期限	number

    "api_key": "string",

    "api_token": "string",

    "expired": timestamp

GET /sensors

センサーの一覧を取得します。クエリパラメータはありません。

Responses(Kiwi technology社製GW配下のセンサーの場合)

Status Code: 200

Name	Description	Data type
sensor_id	センサーID	number
name	センサー名	string
hw_addr	DevAddrまたはDevEUI	string
latest_values	センサーデータの最新値詳細はSensor Data Formatを参照	object
latitude	センサー設置場所の緯度	number
longitude	センサー設置場所の経度	number
custom	ユーザ設定値（JSON形式） PUT /sensors/{sensor_id} で設定	object

    "sensors": [

            "sensor_id": "string",

            "name": "string",

            "hw_addr": "string",

            "latest_values": {

                "string": {

                    "value": number,

                    "timestamp": timestamp

},

            "latitude": number,

            "longitude": number,

            "custom": object

Responses(Kerlink社製GW配下のセンサーの場合)

Status Code: 200

Name	Description	Data type
sensor_id	センサーID	number
name	センサー名	string
deveui	DevEUI	string
latest_values	センサーデータの最新値詳細はSensor Data Formatを参照	object
latitude	センサー設置場所の緯度	number
longitude	センサー設置場所の経度	number
custom	ユーザ設定値（JSON形式） PUT /sensors/{sensor_id} で設定	object

    "sensors": [

            "sensor_id": "string",

            "name": "string",

            "deveui": "string",

            "latest_values": {

                "string": {

                    "value": number,

                    "timestamp": timestamp

},

            "latitude": number,

            "longitude": number,

            "custom": object

GET /sensors/{sensor_id}

指定センサーの個別情報と過去のセンサーデータ(水位など)を取得します。

start_time, end_timeで指定した範囲のセンサーデータを取得できます。
- エポック時間（ミリ秒）を指定します。
- いずれかまたは両方のパラメータが指定されない場合、過去24時間のデータを取得します。
- 一度のリクエストで指定できる範囲は最大で100日です。

Name	Description	Type	Data type	Example	Memo
sensor_id	IIJより指定されたセンサーID値	path	string	s-zz-0000000	required
start_time	履歴データの取得開始エポックミリ秒	query	number	1581562000000
end_time	履歴データの取得最終エポックミリ秒	query	number	1581562500000

Responses(Kiwi社製GW配下のセンサーの場合)

Status Code: 200

sensorキーの要素: センサーの個別情報

Name	Description	Data type
sensor_id	センサーID	number
name	センサー名	string
hw_addr	DevAddrまたはDevEUI	string
latest_values	センサーデータの最新値詳細はSensor Data Formatを参照	object
latitude	センサー設置場所の緯度	number
longitude	センサー設置場所の経度	number
custom	ユーザ設定値（JSON形式） PUT /sensors/{sensor_id} で設定	object

historyキーの要素: 過去のセンサーデータ(Uplink毎)

Name	Description	Data type
hw_addr	sensorのhw_addrと同じ	string
timestamp	センサーデータの時刻エポック時間（ミリ秒）	number
センサーデータ名(可変)	対応するデータ値同じUplinkが複数データを含む場合、同階層に複数キーが並ぶ	string/number

    "sensor": {

        "sensor_id": "string",

        "name": "string",

        "hw_addr": "string",

        "latest_values": {

            "string": {

                "value": value,

                "timestamp": timestamp

},

        "latitude": number,

        "longitude": number,

        "custom": object

},

    "history": [

            "hw_addr": "string",

            "timestamp": timestamp,

            "センサーデータ名(可変)": データ値

Responses(Kerlink社製GW配下のセンサーの場合)

Status Code: 200

sensorキーの要素: センサーの個別情報

Name	Description	Data type
sensor_id	センサーID	number
name	センサー名	string
deveui	DevEUI	string
latest_values	センサーデータの最新値詳細はSensor Data Formatを参照	object
latitude	センサー設置場所の緯度	number
longitude	センサー設置場所の経度	number
custom	ユーザ設定値（JSON形式） PUT /sensors/{sensor_id} で設定	object

historyキーの要素: 過去のセンサーデータ(Uplink毎)

Name	Description	Data type
hw_addr	sensorのdeveuiと同じ Kiwi社製GWの場合と仕様が異なるため注意してください	string
timestamp	センサーデータの時刻エポック時間（ミリ秒）	number
センサーデータ名(可変)	対応するデータ値同じUplinkで到着したデータが複数ある場合、キーが複数付加される	string/number

    "sensor": {

        "sensor_id": "string",

        "name": "string",

        "deveui": "string",

        "latest_values": {

            "string": {

                "value": value,

                "timestamp": timestamp

},

        "latitude": number,

        "longitude": number,

        "custom": object

},

    "history": [

            "hw_addr": "string",

            "timestamp": timestamp,

            "センサーデータ名(可変)": データ値

PUT /sensors/{sensor_id}

指定センサーの個別設定をします。

Name

Description

Type

Data type

Example

Memo

sensor_id

IIJより指定されたセンサーID

path

string

s-zz-0000000

required

name

センサー名

body

string

PaddyDevice

latitude

センサー設置場所の緯度

body

number

12.345

longitude

センサー設置場所の経度

body

number

12.345

custom

ユーザ設定値（JSON形式）
ご自由にお使いください

body

object

	"device_status": 100

Responses(Kiwi社製GW配下のセンサーの場合)

Status Code: 200

Name	Description	Data type
sensor_id	センサーID	number
name	センサー名	string
hw_addr	DevAddrまたはDevEUI	string
latest_values	センサーデータの最新値詳細はSensor Data Formatを参照	object
latitude	センサー設置場所の緯度	number
longitude	センサー設置場所の経度	number
custom	ユーザ設定値（JSON形式）	object

    "sensor": {

        "sensor_id": "string",

        "name": "string",

        "hw_addr": "string",

        "latest_values": {

            "string": {

                "value": number,

                "timestamp": timestamp

},

        "latitude": number,

        "longitude": number,

        "custom": object

Responses(Kerlink社製GW配下のセンサーの場合)

Status Code: 200

Name	Description	Data type
sensor_id	センサーID	number
name	センサー名	string
deveui	DevEUI	string
latest_values	センサーデータの最新値詳細はSensor Data Formatを参照	object
latitude	センサー設置場所の緯度	number
longitude	センサー設置場所の経度	number
custom	ユーザ設定値（JSON形式）	object

    "sensor": {

        "sensor_id": "string",

        "name": "string",

        "deveui": "string",

        "latest_values": {

            "string": {

                "value": number,

                "timestamp": timestamp

},

        "latitude": number,

        "longitude": number,

        "custom": object

変更履歴

日付	変更内容
2026-04-22	Kerlink社GWを利用する場合のレスポンスボディ仕様を追加 ※ 既存のKiwi社GWを利用する場合の仕様は維持するレスポンスボディの仕様説明を追加センサー固有のデータ仕様を追加
2021-04-02	一度の GET /sensors/{sensor_id} で指定できる範囲を最大100日とする
2020-03-25	manual.iij.jpに公開
2020-02-27	POST /sensors および DELETE /sensors/{sensor_id} を廃止 sensor.index を廃止
2020-01-06	POST /sensors および DELETE /sensors/{sensor_id} を廃止予定
2019-12-26	sensor.description を削除 sensor.index を廃止予定
2019-11-28	初版公開

公開
マニュアル一覧へ

ご契約者向け
マニュアル一覧へ

Web API

目次

はじめに

APIエンドポイント

HTTPヘッダ項目

APIパス一覧

注意事項

API詳細仕様

POST /auth

Responses

GET /sensors

Responses(Kiwi technology社製GW配下のセンサーの場合)

Responses(Kerlink社製GW配下のセンサーの場合)

GET /sensors/{sensor_id}

Responses(Kiwi社製GW配下のセンサーの場合)

Responses(Kerlink社製GW配下のセンサーの場合)

PUT /sensors/{sensor_id}

Responses(Kiwi社製GW配下のセンサーの場合)

Responses(Kerlink社製GW配下のセンサーの場合)

変更履歴