このページでは、APIを利用してSmartDrive Platformのデータを参照・更新する方法について解説しています。

Note: このドキュメントは完全ではありません。随時更新していますが、実際の動作との乖離が見つかった場合は ご連絡ください。

全てのAPI呼び出しにはアプリケーショントークンによる認証が必要です。 リクエストの x-api-key ヘッダに設定してご利用ください。

curl --request GET \
  --url 'https://smartdrive-api.com/v1.0/devices/010009/locations?ts_from=2019-01-01T00:00:00Z&ts_to=2019-10-01T00:00:00Z' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \

アプリケーショントークンは、別途お渡しします。

WIP

このAPIはjsonをやり取りするRestfulなAPIです。 PUT/POST/PATCH といった更新系のリクエストのContent-Typeには application/json を指定してください。

このAPIはjsonをやり取りするRestfulなAPIです。 特別な注意書きがない限り、ほとんどのAPIのレスポンスはjsonとなります。 参照系のエンドポイントが /devices のようなコレクションを指し示す場合は、レスポンスのdataはリソースの配列になります。 一度のレスポンスでデータが取得しきれない場合は paging プロパティに次の呼び出し時に使うカーソル情報が設定されます。

{
  "meta": {
    "http_status_code": 200,
    "result": true
  },
  "paging": {
    "next": "MTAxNTExOTQ1MjAwNzI5NDE="
  },
  "data": [
    {
      "code": "07144A",
      "organization": {
        "id": "ZrMa7d5WF6cpsV0ejp29",
        "name": "SmartDrive"
      }
    }
  ]
}

/devices/{device_code} や /devices/{device_code}/last_location のようにリソース自体、もしくはリソースの プロパティを指し示す場合は、レスポンスのdataはオブジェクトになります。

{
  "meta": {
    "http_status_code": 200,
    "result": true
  },
  "data": {
    "ts": "2014-06-02T23:02:34Z",
    "lat": 35.658581,
    "lng": 139.745433,
    "speed": 6,
    "h_accuracy": 10,
    "v_accuracy": 30
  }
}

削除・更新のエンドポイントの場合、レスポンスのdataは作成・更新されたオブジェクトになります。

{
  "meta": {
    "http_status_code": 200,
    "result": true
  },
  "data": {
    "id": "sV2Wcp9FZrMa7d56p0ej",
    "organization": {
      "id": "ZrMa7d5WF6cpsV0ejp29",
      "name": "SmartDrive"
    },
    "name": "東京タワー",
    "address": "東京都港区芝公園４丁目２−８",
    "coordinates": {
      "lat": 35.658581,
      "lng": 139.745433
    },
    "radius": 100
  }
}

削除のエンドポイントの場合、レスポンスのdataは存在しません。

{
  "meta": {
    "http_status_code": 200,
    "result": true
  }
}

APIでエラーが発生した場合は、レスポンスのstatus codeが300以上になります。 また、レスポンスのmetaデータにエラーの詳細が格納されます。

WIP

リソース一覧を取得・検索するAPIのほとんどは、カーソルベースのページネーションが実装されています。

cursor-based pagination

ページング可能なコレクションリソースにおいて、データ量が多く、一度のAPI呼び出しで全てのデータを 取得できないケースでは、レスポンスにpaging.nextというプロパティが設定されます。 次回のAPI呼び出し時にその値を設定することで、残りのデータを取得することができます。 未指定の場合は最初からの取得になります。

各データ型について、特別注釈のない場合の取りうる値は下記のとおりになります。

IoTデバイスを参照・操作するためのエンドポイント。

走行を参照・操作するためのエンドポイント。