利用開始

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

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

注

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

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 が発生します。

次のステップ

ツアー計画 API リファレンスおよび使用例を参照して、さまざまなツアー計画シナリオを確認することをお勧めします。

利用開始

利用開始

注

HERE アカウントの取得

アプリを登録する

API キーを入手

リクエストの送信

注

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

同期リクエスト

非同期リクエスト

注

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

解決策のステータスを確認してください

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

注

次のステップ

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

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

開発者

利用開始

注

HERE アカウントの取得

アプリを登録する

API キー を入手

リクエストの送信

注

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

同期リクエスト

非同期リクエスト

注

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

解決策のステータスを確認してください

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

注

次のステップ

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

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

開発者

API キーを入手

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