はじめに - HERE Developer ポータル

このセクションでは、 HERE Developer ポータルの HERE Tour Planning API を使用してはじめにをすばやく実行する方法について説明します。

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

注

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

HERE アカウントを取得

If you are an individual developer who has signed up for one of the plans listed on our Developer plans page on here-tech.skawa.fun., you received a HERE account ID when you signed up. You can use your HERE account to log in to here-tech.skawa.fun. to create applications. Applications (uniquely identified by an app ID) enable development with HERE products and services.

アプリを登録する

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

Sign in to here-tech.skawa.fun..
名前をクリックし 、 [ プロジェクト] を選択して、一覧からプロジェクトを選択します。プロジェクトの詳細と利用可能なアプリケーションの資格情報が表示されます。
JavaScript または REST を選択し、 Generate アプリをクリックします。アプリケーションが作成されると、そのアプリ ID が表示されます。

API キーを入手

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

Sign in to here-tech.skawa.fun..
名前をクリックし 、 [ プロジェクト] を選択して、一覧からプロジェクトを選択します。プロジェクトの詳細と利用可能なアプリケーションの資格情報が表示されます。
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 Developer ポータル

はじめに - HERE Developer ポータル

注

HERE アカウントを取得

アプリを登録する

API キーを入手

リクエストを送信する

注

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

同期リクエスト

非同期リクエスト

注

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

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

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

注

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

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

開発者

はじめに - HERE Developer ポータル

注

HERE アカウントを取得

アプリを登録する

API キー を入手

リクエストを送信する

注

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

同期リクエスト

非同期リクエスト

注

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

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

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

注

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

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

開発者

API キーを入手

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