このセクションでは、 HERE platform の HERE Tour Planning API を使用して実行する方法について説明します。

HERE アカウントを取得
アプリを登録する
API キーを入手
リクエストを送信

注

このセクションでは、 HERE Tour Planning API の使用を迅速に開始するために必要な最小限の設定について説明します。HERE アカウントの設定、アプリの登録、および認証の詳細については、『 Identity & Access Management 開発者ガイド』を参照してください。

HERE アカウントを取得

組織が HERE Workspace または HERE Marketplace にサインアップしている場合は、組織の管理者に連絡して、会社に設定されている HERE platform 組織の参加を招待をしてもらってください。組織が設定されていない場合は、 HERE platform の無料試用版をリクエストすることもできます。詳細については、 HERE platform の価格表を参照してください。

アプリを登録する

アプリを登録するには、次の手順を実行します。

HERE アカウントを使用して HERE platform にサインインする。
ランチャから [アクセスマネージャ]を開きます。
[アプリ] タブで、 [新しいアプリを登録] をクリックし、要求された情報を入力します。
[ 登録] をクリックするプラットフォームによって、一意のアプリ ID を持つ新しいアプリが作成されます。

APIキーを取得

API キーを取得するには、次の手順を実行します。

HERE アカウントを使用して HERE platform にサインインする。
ランチャから [アクセスマネージャ]を開きます。
[ アプリ ] タブで、前のセクションで作成したアプリ、アプリの登録、または API キーを生成する既存のグループアプリをクリックする。
[資格情報]タブでタブで、[API Keys] を選択し、 [API キーを生成]をクリックして、アプリケーション認証資格情報用に最大 2 つのAPI キーを生成します。API キーが作成され、表示されます。

リクエストを送信する

HERE Tour Planning API は、同期および非同期の 2 種類のリクエストをサポートしています。すべてのフィーチャーは同期リクエストと非同期リクエストの両方で使用できますが、同期要求には、ジョブおよび運行管理サイズに対するより厳しい制限があります。

注

車両の取り回しの問題を解決するには、一部の機能がより困難になります。そのため、「適切な」解決策を見つけるには、アルゴリズムにより多くの時間が必要になります。このような機能には、作業量および車両タイプ、複数作業、集荷および配達作業、制限時間帯、総作業量と比較した車両総積載量の不足などがあります。 HERE では、このような場合にポーリング間隔が長くなる非同期要求を使用することを推奨しています。

問題の解決にかかる時間と比べて複雑です

特定のフィーチャーでは、車両の取り回しの問題をより困難にしているため、「適切な」解決策を見つけるためにアルゴリズムにより多くの時間が必要になります。そのようなフィーチャーは次のとおりです

作業量と車両タイプ：量が大きいほど、問題がより複雑になります
複数のジョブ
集荷と配達のジョブ
制限時間帯
総作業量に対して車両総積載量が不足しています

このような場合は、ポーリング間隔が長くなっている非同期リクエストを使用することを検討してください。

同期リクエスト

同期リクエストを使用するには、サーバーにリクエストを送信し、レスポンスを待っている必要があります。同期リクエストのジョブ数は 250 件、車両タイプは 35 件に制限されています。大きな問題の場合は、非同期リクエストを使用できます。

問題定義を作成し、対応するエンドポイントに解決策の計算リクエストを送信します。リクエストが有効な場合、サービスは計算を開始し、計算が完了すると解決策を返します。このようなリクエストの例を次に示します。

POST https://tourplanning.hereapi.com/v3/problems
Authorization: Bearer <TOKEN>
Content-Type: application/json

本文 :

{
  "plan": {
    "jobs": [
      {
        "id": "myJob",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {"lat": 52.46642, "lng": 13.28124},
                  "times": [["2020-07-04T10:00:00.000Z","2020-07-04T12:00:00.000Z"]],
                  "duration": 180
                }
              ],
              "demand": [1]
            }
          ]
        }
      }
    ]
  },
  "fleet": {
    "types": [
      {
        "id": "myVehicleType",
        "profile": "normal_car",
        "costs": {
          "distance": 0.0002,
          "time": 0.005,
          "fixed": 22
        },
        "shifts": [{
          "start": {
            "time": "2020-07-04T09:00:00Z",
            "location": {"lat": 52.52568, "lng": 13.45345}
          },
          "end": {
            "time": "2020-07-04T18:00:00Z",
            "location": {"lat": 52.52568, "lng": 13.45345}
          }
        }],
        "limits": {
          "maxDistance": 300000,
          "shiftTime": 28800
        },
        "capacity": [10],
        "amount": 1
      }
    ],
    "profiles": [{
      "name": "normal_car",
      "type": "car",
      "departureTime": "2020-07-04T09:15:00Z"
    }]
  },
  "configuration": {
    "termination": {
      "maxTime": 2,
      "stagnationTime": 1
    }
  }
}

計算された解決策を使用したレスポンスの例 :

{
  "statistic": {
    "cost": 54.459916,
    "distance": 35277,
    "duration": 5286,
    "times": {
      "driving": 5106,
      "serving": 180,
      "waiting": 0,
      "break": 0
    }
  },
  "tours": [
    {
      "vehicleId": "myVehicle_1",
      "typeId": "myVehicle",
      "stops": [
        {
          "location": {"lat": 52.52568, "lng": 13.45345},
          "time": {
            "arrival": "2020-07-04T09:19:01Z",
            "departure": "2020-07-04T09:19:01Z"
          },
          "load": [1],
          "activities": [
            {
              "jobId": "departure",
              "type": "departure"
            }
          ]
        },
        {
          "location": {"lat": 52.46642, "lng": 13.28124},
          "time": {
            "arrival": "2020-07-04T10:00:00Z",
            "departure": "2020-07-04T10:03:00Z"
          },
          "load": [0],
          "activities": [
            {
              "jobId": "myJob",
              "type": "delivery"
            }
          ]
        },
        {
          "location": {"lat": 52.52568, "lng": 13.45345},
          "time": {
            "arrival": "2020-07-04T10:47:07Z",
            "departure": "2020-07-04T10:47:07Z"
          },
          "load": [0],
          "activities": [
            {
              "jobId": "arrival",
              "type": "arrival"
            }
          ]
        }
      ],
      "statistic": {
        "cost": 54.459916,
        "distance": 35277,
        "duration": 5286,
        "times": {
          "driving": 5106,
          "serving": 180,
          "waiting": 0,
          "break": 0
        }
      }
    }
  ]
}

詳細については、「ソリューション」を参照してください。

リクエストが有効でない場合は、対応するエラーが返されます。

{
  "title": "BAD_REQUEST",
  "status": 400,
  "code": "E613420",
  "cause": "Vehicle's arrival time is earlier than its departure time",
  "action": "Correct arrival time of 'vehicle' to be earlier than its departure",
  "correlationId": "<globally unique id>"
}

非同期リクエスト

問題の解決策を受け取る非同期リクエストは、次のいくつかの手順で構成されます。

問題の解決策をリクエストします
ソリューションのステータスを確認します
ソリューションをダウンロードします

注

非同期リクエストのフローには、 3000 件のジョブと 150 件の車両タイプの制限があります。

問題の解決策をリクエストします

問題定義を作成し、対応するエンドポイントに解決策の計算リクエストを送信します。

POST https://tourplanning.hereapi.com/v3/problems/async
Authorization: Bearer <TOKEN>
Content-Type: application/json

本文 :

{
  "plan": {
    "jobs": [
      {
        "id": "myJob",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {"lat": 52.46642, "lng": 13.28124},
                  "times": [["2020-07-04T10:00:00.000Z","2020-07-04T12:00:00.000Z"]],
                  "duration": 180
                }
              ],
              "demand": [1]
            }
          ]
        }
      }
    ]
  },
  "fleet": {
    "types": [
      {
        "id": "myVehicleType",
        "profile": "normal_car",
        "costs": {
          "distance": 0.0002,
          "time": 0.005,
          "fixed": 22
        },
        "shifts": [{
          "start": {
            "time": "2020-07-04T09:00:00Z",
            "location": {"lat": 52.52568, "lng": 13.45345}
          },
          "end": {
            "time": "2020-07-04T18:00:00Z",
            "location": {"lat": 52.52568, "lng": 13.45345}
          }
        }],
        "limits": {
          "maxDistance": 300000,
          "shiftTime": 28800
        },
        "capacity": [10],
        "amount": 1
      }
    ],
    "profiles": [{
      "name": "normal_car",
      "type": "car",
      "departureTime": "2020-07-04T09:15:00Z"
    }]
  },
  "configuration": {
    "termination": {
      "maxTime": 2,
      "stagnationTime": 1
    }
  }
}

サービスは、次のレスポンス本文を返します。

{
    "statusId": "<globally unique id>",
    "href": "https://tourplanning.hereapi.com/v3/status/<same as in statusId>"
}

レスポンスの要素は次のとおりです。

statusId ：ステータスの一意の識別子。ソリューションの計算ステータスの追跡、および解決策の結果のダウンロードに使用されます。
href ーステータスをポーリングするための URL 。

ソリューションのステータスを確認します

特定の問題 ID の解の計算ステータスを取得するには、リクエストの送信時に取得した hrefを使用します。

> GET https://tourplanning.hereapi.com/v3/status/<statusId>
> Authorization: Bearer <token>
---
< HTTP/1.1 200 OK
< Content-Type: application/json

本文 :

{
    "status": "pending"
}

ステータス pending またはinProgressを取得した場合は、計算が完了し、ステータスが、 success、timeout、またはfailureに戻るまでポーリングを続行する必要があります。

successのレスポンスは、計算された解決策をダウンロードするためのリソースリンクを返します。

{
    "status": "success",
    "resource": {
      "resourceId": "<globally unique id>",
      "href": "https://tourplanning.hereapi.com/v3/problems/<same as resourceId>/solution"
    }
}

failureのレスポンスはエラーオブジェクトを返します。

{
    "status": "failure",
    "error": {
      "message": "There was an error solving the problem"
    }
}

statusIdを使用すると、次のセクションで説明するように、ソリューションエンドポイント経由でエラーの詳細を取得できます。

ソリューションをダウンロードします

解決策の計算のステータスが success の場合、計算された解は、実質的に problemId である要素resourceIdで指定された ID を使用して利用できます。

> GET https://tourplanning.hereapi.com/v3/problems/<problemId>/solution
> Content-Type: application/json

レスポンス本文 :

{
  "statistic": {
    "cost": 54.459916,
    "distance": 35277,
    "duration": 5286,
    "times": {
      "driving": 5106,
      "serving": 180,
      "waiting": 0,
      "break": 0
    }
  },
  "tours": [
    {
      "vehicleId": "myVehicle_1",
      "typeId": "myVehicle",
      "stops": [
        {
          "location": {"lat": 52.52568, "lng": 13.45345},
          "time": {
            "arrival": "2020-07-04T09:19:01Z",
            "departure": "2020-07-04T09:19:01Z"
          },
          "load": [1],
          "activities": [
            {
              "jobId": "departure",
              "type": "departure"
            }
          ]
        },
        {
          "location": {"lat": 52.46642, "lng": 13.28124},
          "time": {
            "arrival": "2020-07-04T10:00:00Z",
            "departure": "2020-07-04T10:03:00Z"
          },
          "load": [0],
          "activities": [
            {
              "jobId": "myJob",
              "type": "delivery"
            }
          ]
        },
        {
          "location": {"lat": 52.52568, "lng": 13.45345},
          "time": {
            "arrival": "2020-07-04T10:47:07Z",
            "departure": "2020-07-04T10:47:07Z"
          },
          "load": [0],
          "activities": [
            {
              "jobId": "arrival",
              "type": "arrival"
            }
          ]
        }
      ],
      "statistic": {
        "cost": 54.459916,
        "distance": 35277,
        "duration": 5286,
        "times": {
          "driving": 5106,
          "serving": 180,
          "waiting": 0,
          "break": 0
        }
      }
    }
  ]
}

詳細については、「ソリューション」を参照してください。

問題の解決中にエラーが発生した場合は、次のエラーレスポンスが返されます。

{
    "title": "Unprocessable entity",
    "status": 422,
    "code": "E613000",
    "cause": "E613420, 'Vehicle's arrival time is earlier than its departure time' 'Correct arrival time of 'vehicle' to be earlier than its departure'",
    "action": "",
    "correlationId": "REQ-497fdde4-048d-4db5-9d6e-8e44a952dede"
}

注

未完了の計算の解決策をリクエストすると、 HTTP ステータスコード 404 Not Found が発生します。

利用開始:HERE platform

注

HERE アカウントを取得

アプリを登録する

APIキーを取得

リクエストを送信する

注

問題の解決にかかる時間と比べて複雑です

同期リクエスト

非同期リクエスト

注

問題の解決策をリクエストします

ソリューションのステータスを確認します

ソリューションをダウンロードします

注

「」に一致する結果は件です

「」に一致する結果はありません

開発者

注

HERE アカウントを取得

アプリを登録する

APIキーを取得

リクエストを送信する

注

問題の解決にかかる時間と比べて複雑です

同期リクエスト

非同期リクエスト

注

問題の解決策をリクエストします

ソリューションのステータスを確認します

ソリューションをダウンロードします

注

「」に一致する結果は 件です

「」に一致する結果はありません

開発者

「」に一致する結果は件です