サードパーティ製アプリケーションのルートをLiveloxと統合する

ご自身のアプリケーションをLiveloxと統合することでルートデータのシームレスな転送が可能になり、アスリートが記録した移動軌跡をLiveloxプラットフォーム上に自動的に表示させることができます。本ガイドでは、プログラムによってルートを送信する際に関連する概念、認可要件、およびAPIエンドポイントの概要について説明します。

用語定義（Terminology）

• Route（ルート） – アスリートの移動を示す（日時, 緯度, 経度）のタプル（組）のリストを含むGPSトラックデータ
• Route providing application（ルート提供元アプリケーション） – ルートを生成・提供するWebアプリまたはモバイルアプリなどのアプリケーション
• Importable route（インポート可能ルート） – Liveloxへインポートするために、ルート情報とその他のメタデータを組み合わせたJSONオブジェクト

認可（Authorization）

APIを使用するには認可が必要です。routes.import スコープを使用してください。

詳細については、メインAPIドキュメントページを参照してください。

インポート可能ルート用 APIエンドポイント

{
    // リクエストで提供されたアプリケーション側のルート固有識別子（未提供の場合はLiveloxが自動生成した固有識別子）
    // この値は常に文字列（string）となります。インポート可能ルートオブジェクトで数値の id を提供した場合も同様です
    "id": "123456"
}

{
    // インポートのステータス
    // pending: インポート可能ルートを受信したが、まだインポート処理は完了していない
    // imported: インポートが正常に完了した
    // error: 何らかの理由でインポートに失敗した（詳細は errorMessage プロパティを確認）
    "status": "imported",

    // Liveloxビューアーでオリエンテーリングマップ上にルートを表示するためのURL（status が imported の場合のみ設定）
    "viewerUrl": "https://www.livelox.com/Viewer/...",

    // Liveloxでのイベントやクラスへの紐付け情報など、ルートとその属性を表示するためのURL（status が imported の場合のみ設定）
    "showRouteUrl": "https://www.livelox.com/Sessions/Show/...",

    // Liveloxでのイベントやクラスへの紐付け情報など、ルートとその属性を編集するためのURL（status が imported の場合のみ設定）
    "editRouteUrl": "https://www.livelox.com/Sessions/Edit/...",

    // ルートが紐付けられたLiveloxイベントの名称（紐付けがある場合）
    "eventName": "Sample event",

    // ルートが紐付けられたLiveloxイベント内のクラス名（紐付けがある場合）
    "className": "Sample class",

    // ルートのインポートが失敗した理由（status が error の場合のみ設定）
    "errorMessage": "Invalid route format"
}

インポート可能ルートオブジェクト（The importable route object）

{
    // アプリケーション側で管理するルートの固有識別子
    // 未設定の場合、Liveloxが独自の固有識別子を生成します
    // 整数、または最大48文字の文字列を指定可能です
    // 同じ固有識別子を持つインポート可能ルートを再送信（POST）すると、以前のルートデータが上書きされます
    // 内部処理として、Liveloxはこの識別子の先頭にルートを送信したユーザーの識別子を付与します
    "id": 123456,

    // Base64でエンコードされたGPSルートファイルデータ
    // サポートされているファイル形式: GPX, TCX, FIT
    "data": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPGdweCB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnRvcG9ncmFmaXguY29tL0dQWC8xLzEiPgogICAuLi4KPC9ncHg+",

    // オプション: ルートを記録したデバイス/ハードウェアのモデル名
    "deviceModel": "Fancy Gadget X123",

    // オプション: ルートを記録した人物に関する情報
    // APIキーを使用してリクエストを行う場合のみ使用されます
    "person": {
        "firstName": "John",
        "lastName": "Doe"
    },

    // オプション: 紐付けるLiveloxのクラスID（判明している場合）
    // クラスIDを取得するには、GET https://api.livelox.com/events または GET https://api.livelox.com/events/{eventId} エンドポイントを使用します
    // クラスIDが指定されない場合、Liveloxはルートの日時や地理的エリアに該当するクラス・コースとルートを照合し、
    // 十分に一致するものが見つかれば、そのクラスへ自動的に紐付けます
    "classId": 123456
}