﻿======================================================================
             SfeerUserAPI 仕様 ver. 1.1.0
======================================================================

<< Version履歴 >>
2010-4-1 ver.1.0.0　戸辺，藤田，岩井，大島
2010-4-8 ver.1.1.0　大島
2010-4-13 ver.1.1.1 岩本，岩井，松本，梅田，大島

<< 更新履歴 >>
2010-4-1 ver.1.0.0　SfeerUserAPI策定
2010-4-8 ver.1.1.0　JSONスキーマ変更
2010-4-13 ver.1.1.1　人流のspeed単位＋ResistrationResponse時のrの単位

0. メモ
＜関連項目＞ TomuCoreUserAPI(SfeerサーバがTomuCoreのユーザとなる)

1.はじめに
 Sfeerサーバ－クライアント間の通信形式，データ形式をSfeerUserAPIとして定義する．
 Sfeerクライアント(SfeerView)とSfeerサーバが
 セッションを開始するために取り交わすメッセージを「Registration」とする．
 SfeerクライアントからSfeerサーバへ送られるメッセージを「Request」とする．
 Requestに対して，SfeerサーバからSfeerクライアントへ送られるメッセージを「Response」とする．

2.通信スタイル
 Sfeerサーバ－クライアント間
    [Request] ⇒ HTTP (POSTでサーバへJSONを送信)
    [Response] ⇒ HTTP (POSTに対する返答でクライアントへJSONを送信)
 Sfeerサーバ－TomuCore間
    [Request] ⇒ XMPP (TomuCoreUserAPI準拠のXMLをTomuCoreへ送信)
    [Response] ⇒ XMPP (TomuCoreUserAPI準拠のXMLをSfeerサーバへ送信)

 最新データの取得はポーリングによって行う．

3.各データ要素
 データ形式はJSONフォーマットに従う．

 3.1 Requestメッセージ
  1つのクエリに複数のエリア，センサタイプの指定が可能．
  ver1では
    - AreaIDはstaticに決め打ち．
    - 時間指定はCurrentのみ．

   ＜ヘッダ情報 Head＞（Required）
    ・sfeerClientId [型:long] (Registration時にサーバからUNIX timeをもらう)
    ・requestMsgId [型:long] (メッセージ送信時UNIX Timeを利用)
    ・apiVersion [型:String]

   ＜AreaId＞
    ・areaId [型:int] (0=ALL, 1, 2, 3, 4, …)

   ＜SensorType＞
    ・sensorType [型:String] (TEMP，PEDESTRIAN，IMAGE)

   //＜SensedTime＞
   // ・sensedTime [型:long] (ver1.0.0ではCURRENTのみなので省略)

 3.2 Responseメッセージ
  1つのRequestに対して，1つのResponseメッセージとなる．
  Areaのセンサは代表となるセンサ1つを返す．
  前回のRequestから値が変化していない場合は，
   -プリミティブ型の場合，-1といった通常とりえない値を入れる．
   -オブジェクト型の場合，nullを代入する．

   ＜ヘッダ情報 Head＞（Required）
    ・sfeerClientId [型:long] (Registration時にサーバからUNIX timeをもらう)
    ・sfeerServerId [型:long]
    ・requestMsgId (RequestのMsg送信時刻) [型:long]
    ・apiVersion [型:String]

   ＜AreaResults＞（Required）
    ・areaID [型:int]
    ・imageValue [型:ImageSet] (指定なしはnull)
    ・pedestrianValue [型:Pedestrian] (指定なしはnull)
    ・tempValue [型:Temperature] (指定なしはnull)

   ＜各Valueの値＞
     tempValue(温度 0時スタート24時間リセット)
       ・type [型:String] (TEMP)
       ・value [型:double] (現在の温度)
       ・max [型:double] (今日の最高気温)
       ・min [型:double] (今日の最低気温)
       ・average [型:double] (今日の平均気温)
       ・incrementalIndex [型:double] (5分間分のデータに対して)

     pedestrianValue(人流)
       ・type [型:String] (PEDESTRIAN)
       ・flowNumber [型:int] (現在の人流)
       ・resident [型:int] (現在の滞留人数)
       ・average [型:double] (直近過去1時間の平均)
       ・incrementalIndex [型:double] (5分間分のデータに対して)
       (以下3要素のリストを必要に応じて4つまで)
       ・compass [型:String] (NORTH，EAST，SOUTH，WEST)
       ・number [型:int] (compassに対する人流)
       ・speed [型:double] (compassに対する人流の平均速度[m/s])

     imageValue(カメラ)
       ・type [型:String] (IMAGE)
       (以下3要素のリスト 最大6つ : 現在1枚 + 過去5枚)
       ・imageUrl [型:String] (画像のURL)
       ・thumbnailUrl [型:String] (サムネイル画像のURL 120×90)
       ・sensedTime [型:long] (撮影時刻)

 3.3 Registration Requestメッセージ
  Sfeerサーバ－クライアント間でセッションを開始するためのメッセージ．

   ＜ヘッダ情報＞（Required）
    ・apiVersion [型:String]

 3.4 Registration Responseメッセージ
  APIVersionがマッチした際に，ClientIDやAreaリストを発行する．

   ＜ヘッダ情報＞（Required）
    ・sfeerClientId [型:long] (サーバはUNIX timeを発行)
    ・sfeerServerId [型:long]
    ・apiVersion [型:String]
    ・areaIdList [型:Area]

   ＜Area情報＞（Required）
    ・areaID [型:int]
    ・areaName [型:String]
    ・lat [型:double]
    ・lon [型:double]
    ・r [型:int] (LatLonポイントからの半径[m])
    ・sessionTimeout [型:long(単位:秒)] (ver1.0.0では1時間[3600秒]で固定)

4. 詳細規定
＜Requestメッセージの例＞
{
  "areaIdSet":[
                {"areaId":1,"type":["TEMP"]},
                {"areaId":2,"type":["TEMP", "PEDESTRIAN"]},
                {"areaId":3,"type":["IMAGE"]}
              ],
  "head":{
           "apiVersion":"1.0.0",
           "requestMsgId":1270744761312,
           "sfeerClientId":1270744761312
         }
}

＜Responseメッセージの例＞
{
  "areaResults":[
                  {
                    "areaId":1,
                    "imageValue":null,
                    "pedestrianValue":null,
                    "tempValue":{
                                  "average":33.3,
                                  "incrementalIndex":10.4,
                                  "max":36.3,"min":30.7,
                                  "type":"TEMP",
                                  "value":35.0
                                }
                  },
                  {
                    "areaId":2,
                    "imageValue":null,
                    "pedestrianValue":{
                                        "average":3.4,
                                        "flowNumber":10,
                                        "flowParams":[
                                                       { "compass":"north", "number":4, "speed":4.5 },
                                                       { "compass":"south", "number":6, "speed":2.2 }
                                                     ],
                                        "incrementalIndex":2.2,
                                        "resident":3,"type":"PEDESTRIAN"
                                      },
                    "tempValue":{
                                  "average":33.3,
                                  "incrementalIndex":10.4,
                                  "max":36.3,"min":30.7,
                                  "type":"TEMP",
                                  "value":35.0
                                }
                  },
                  {
                    "areaId":3,
                    "imageValue":{
                                   "images":[
                                              {
                                                "imageUrl":"http://hoge/hoge1.jpg",
                                                "sensedTime":1270753594984,
                                                "thumbnailUrl":"http://hoge/hoge1_s.jpg"
                                              },
                                              {
                                                "imageUrl":"http://hoge/hoge2.jpg",
                                                "sensedTime":1270753594984,
                                                "thumbnailUrl":"http://hoge/hoge2_s.jpg"
                                              },
                                              {
                                                "imageUrl":"http://hoge/hoge3.jpg",
                                                "sensedTime":1270753594984,
                                                "thumbnailUrl":"http://hoge/hoge3_s.jpg"
                                              }
                                            ],
                                   "type":"IMAGE"
                                 },
                    "pedestrianValue":null,
                    "tempValue":null
                  }
                ],
  "head":{
           "apiVersion":"1.0.0",
           "requestMsgId":1270753594968,
           "sfeerClientId":1270753594968,
           "sfeerServerId":1270753594968
         }
}


＜RegistrationRequestメッセージの例＞
  GETパラメータとしてSfeerサーバへアクセス．
    http://serverhost/register?sfeerAPI=1.0.0

＜RegistrationResponseメッセージの例＞
{
  "areaIdList":[
                 { "areaId":1, "areaName":"交差点A", "lat":1.4, "lon":5.9, "r":40, "sessionTimeout":3600 },
                 { "areaId":2, "areaName":"交差点B", "lat":123.4, "lon":25.1, "r":10, "sessionTimeout":3600 },
                 { "areaId":3, "areaName":"交差点C", "lat":1.9, "lon":112.5, "r":10, "sessionTimeout":3600 }
               ],
  "head":{
           "apiVersion":"1.0.0",
           "requestMsgId":1270744761343,
           "sfeerClientId":1270744761343
         }
}

5. FFS
 MyAreaや時刻指定等々，発展項目は後のバージョンで対応予定．

                                                                 以上