Nature Inc.

はじめに #

Nature Remo Cloud API (以降API) を利用することで、Nature Remoシリーズのセンサーから得られる情報を取得する、Nature Remoから赤外線を送信する、Nature Remo Eシリーズに接続したスマートメーターから得られる電力データを取得する、などのアクションを行うことができます。

APIは、HTTPクライアントがNatureのサーバへHTTPSリクエストを行うことで利用できる。レスポンスはJSON形式です。

Nature Remo クラウドがインターネットに向けて提供するAPIの詳細は API仕様 [Cloud API] を、Nature Remoデバイスがローカルネットワークに提供するローカルのAPIの詳細は API仕様 [Local API] を参照してください1。技術的な問い合わせはNature開発者コミュニティにてお問い合わせ下さいませ。

API の利用条件等は Nature サービス利用規約 に準拠するものとします。利用前に内容を確認し、同意の上で利用してください。また、法人につきましても商用利用前の検証段階に限りAPIの利用を許可するものとします。商用利用のご検討につきましては、Nature API のフォームからお問い合わせくださいませ。

OAuth2 #

認証、認可にはOAuth2を利用します。 APIを利用する際には、必ず以下のHTTPヘッダを付加してください。

Authorization: Bearer {TOKEN}

{TOKEN} 部には、OAuth2を通して取得したアクセストークンを入れてください。 自分のアクセストークンは、home.nature.globalより新規発行や失効することができます。

エラー #

APIを利用したアクションの結果は、HTTPステータスコードで表します。 HTTPステータスコードの意味については、RFC7231を参照してください。

バージョニング #

APIを利用してアクションを行う際には、 GET または POST リクエストを、APIドキュメント swagger.nature.global に記載の path に対して発行します。

path 内の {VERSION} はアクション毎に更新されます。 {VERSION} が変わらなければ、その特定のアクションに対して、ドキュメントに記載されているパラメータの範囲内で、必須リクエストパラメータの追加及び既存のレスポンスパラメータの削除、仕様変更は行いません。

必須リクエストパラメータの追加、レスポンスパラメータの削除、仕様変更が必要な際には、新しい {VERSION} 番号を決定しその {VERSION} を含む path へのリクエストには新しい仕様にしたがってアクションを行います。Nature, Inc.からの告知の後、一定期間 を経て古い {VERSION} に対するリクエストはステータスコード 404 を返します。

リクエスト制限 #

サーバはNatureアカウント(メールアドレスで一意に特定する)につき 5分以内に30回 以上のリクエストを受けるとその後ステータスコード 429 を返します。

お客様の要件によりこの制限は緩和することができます。Natureの担当者にご連絡ください。

以下のHTTPリクエストのレスポンスヘッダで最新の制限状態を確認できます。

  • X-Rate-Limit-Limit : 5分以内に受けられるリクエスト数の上限です。5分以内に30回の制限がかかっている場合には、X-Rate-Limit-Limitは30となります。
  • X-Rate-Limit-Reset : リクエスト数の制限をリセットする時刻を表すepoch timeです。この時刻を過ぎると、次のリセット時刻までにX-Rate-Limit-Limitの数のリクエストを受けられます。epoch timeについては詳しくはUNIX時間Wikipediaをご確認ください。
  • X-Rate-Limit-Remaining : X-Rate-Limit-Resetの時刻までに受けられる残りリクエスト数を表します。X-Rate-Limit-Reset直後にはX-Rate-Limit-Limitと一致し、リクエストを受けるたびに数が減っていきます。

ECHONET Liteに関連するAPIのリクエスト制限 #

以下のECHONET Liteに関連するエンドポイントについては、さらに追加のリクエスト制限を行います。

これらのエンドポイントを呼び出すと、NatureサーバはNature Remo Eを通してECHONET Lite家電に対して上記の要求を送ります。

ECHONET Lite家電からNature Remo Eを通してNatureサーバへ応答が返ってこない場合には、最大のインターバルを20秒として、同じECHONET Lite家電についての、上記エンドポイントへのリクエストにはステータスコード 429 を返します。 応答が返ってこない場合でも、20秒を超えれば再度リクエストを受け付けます。 応答が返ってきた場合には、20秒以内でも再度リクエストを受け付けます（ただし5分以内に30回の制約はここでも有効）。 この制限は家電単位で行います。

この制限によりステータスコード 429 が返る場合には、上記リクエスト制限の項同様に X-Rate-Limit-Limit, X-Rate-Limit-Reset, X-Rate-Limit-Remaining のヘッダでリクエスト制限の状況を確認できます。

応答が返ってきたことは GET /1/echonetlite/appliances のレスポンスに含むECHONET Liteプロパティについての updated_at が表す時刻を見ることで確認できます。

  1. Nature Remo nano は Local API 非対応、Nature Remo Lapis は今後 Local API に対応予定です。 ↩︎

Copyright © 2017- Nature Inc.