ガイドAPIリファレンス
ガイド
  1. HERE Matrix Routing API V8の概要

HERE Matrix Routing API v8の使用を開始する

このセクションでは、HEREプラットフォームでMatrixRoutingサービスの使用を速やかに開始する方法について説明します。

📘

注

このセクションでは、速やかにMatrix Routingサービスの使用を開始するうえで必要な最小限の設定について説明します。HEREアカウントの設定、プロジェクトの作成、アプリの登録、認証の詳細については、「Identity and Access Managementのガイド」を参照してください。

HEREアカウントを取得する

組織管理者からの招待状を通じて、または無料で利用を開始して、HEREプラットフォームへのアクセスを入手します。

  • 会社がすでにHEREプラットフォーム組織を設立している場合は、組織への参加に招待できる管理者に連絡してください。
  • 会社がまだHEREプラットフォーム組織を設立していない場合は、無料で利用を開始できます。詳細については、「HEREプラットフォームの価格設定」を参照してください。

APIキーを入手する

APIキーを取得するには、まずアプリを作成する必要があります。アプリを作成するには、次の手順を実行します。

  1. HEREアカウントを使用してHEREプラットフォームにサインインします。
  2. ランチャーから[アクセスマネージャー]を開きます。
  3. タブ[アプリ]を選択します。
  4. [新しいアプリを登録]をクリックします。
  5. アプリの名前を入力します。
  6. [プロジェクトへのデフォルトのアクセス権]で、[No Project](プロジェクトなし) を選択します。
  7. [登録]をクリックします。

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

  1. HEREアカウントを使用してHEREプラットフォームにサインインします。
  2. ランチャーから[アクセスマネージャー]を開きます。
  3. タブ[アプリ]を選択します。
  4. [アプリ]タブのリストにあるアプリ名をクリックしてアプリを開きます。
  5. タブ[資格情報]を選択します。
  6. [APIキー]をクリックします。
  7. [API キーを作成]をクリックします。

リクエストを送信する

Matrix Routingは同期リクエストまたは非同期リクエストで実行できます。すべてのモードは同期リクエストと非同期リクエストの両方で使用できますが、同期リクエストにはマトリックスのサイズに対する追加の制限があります。使用可能なモードの詳細については、次のチュートリアルを参照してください。

リクエストのタイプに応じて、異なる手順を実行する必要があります。リクエストタイプに関係なく、regionDefinitionを指定する必要があります。出発地と目的地を含むリージョンを定義できます。または、自分でリージョンを定義しない場合は、単にregionDefinitionタイプとしてautoCircleをリクエストします。詳細については、「リージョンとregionDefinition」を参照してください。

任意の長さのルートを含むマトリックスを計算する場合は、地域定義worldを使用します。この場合、事前定義されたプロファイルIDのいずれかを指定するか、またはカスタムオプションを定義する場合はマトリックスのサイズを制限する必要があります。詳細については、「マトリックス計算のプロファイル」を参照してください。

同期リクエスト

同期APIを使用するということは、マトリックス計算リクエストをサーバーに送信してレスポンスを待つことを意味します。同期リクエストには、マトリックスの次元に関するさらなる制限があります。

同期マトリックス計算をリクエストするには、asyncクエリパラメーターをfalseの値に設定します。それ以外の場合、同期マトリックスリクエストの内容は非同期リクエストの内容と同じになります。

次に、マトリックス計算リクエストを送信します。サービスはリクエストを検証し、リソースがマトリックスの計算で使用できるようになるまでキューに追加します。計算が終了したとき、またはエラーが発生した場合には、サービスはマトリックス結果を直接返します。

次の例のクエリパラメーターasync=falseに留意してください。

📘

注

認証方式に応じて、表示されているここでのリクエストの例に、Bearerトークンまたはクエリパラメーターを含むAuthorizationヘッダーを追加する必要があります。

詳細については、「Identity and Access Managementのガイド」を参照してください。

POST https://matrix.router.hereapi.com/v8/matrix?async=false
Content-Type: application/json
Body:
{
    "origins": [{"lat": 0.0, "lng": 0.0}, {"lat": 0.1, "lng": 0.1}, ...],
    "destinations": [...],  // if omitted same as origins
    "regionDefinition": {
        "type": "circle",
        "center": {"lat": 0.0, "lng": 0.0},
        "radius": 10000
    }
}

ステータスコード200を受け取った場合、リクエストは正常に計算されています。

マトリックス結果の構造は次のとおりです。

{
    "matrixId": "{matrixId}",
    "matrix": {
        "numOrigins": 10,
        "numDestinations": 1000,
        // 10,000 travel times
        // entry k corresponds to origin i and destination j by the formula:
        // k = num_destinations * i + j
        "travelTimes": [10, 20, 0, ...],
        "errorCodes": [0, 0, 0, ...]   // error for each pair of (origin, dest) if any
    },
    // same as request
    "regionDefinition": {
        "type": "circle",
        "center": {"lat": 0.0, "lng": 0.0},
        "radius": 10000
    }
}

マトリックス結果には計算されたルーティングマトリックスに加えて、次が含まれます。

  • matrixId - マトリックスの一意の識別子。
  • regionDefinition - マトリックスの計算に使用されるリージョン定義。ユーザーが指定したもの、または自動的に派生したもの (autoCircleがリクエストされた場合) のいずれかです。

非同期リクエスト

非同期APIを使用する場合、完全なマトリックス計算サイクルはサービスへの複数のリクエストで構成されます。

  • マトリックス計算リクエスト。
  • 計算ステータスのポーリング。
  • マトリックス結果のダウンロード。

マトリックス計算をリクエストする

新しいマトリックス計算リクエストを作成します。リクエストが有効な場合、サービスがリクエストをすべてのマトリックス計算のキューに追加し、リソースが使用可能になると計算を開始します。

📘

注

認証方式に応じて、表示されているここでのリクエストの例に、Bearerトークンまたはクエリパラメーターを含むAuthorizationヘッダーを追加する必要があります。

詳細については、「Identity and Access Managementのガイド」を参照してください。

> POST https://matrix.router.hereapi.com/v8/matrix
> Authorization: Bearer <token>
> Content-Type: application/json

JSONリクエストボディの場合：

{
    "origins": [{"lat": 0.0, "lng": 0.0}, {"lat": 0.1, "lng": 0.1}, ...],
    "destinations": [...],  // if omitted, origins are used as destinations
    "regionDefinition": {
        "type": "circle",
        "center": {"lat": 0.0, "lng": 0.0},
        "radius": 10000
    }
}

上のリクエストに対するレスポンスは次のとおりです。

{
    "matrixId": "<globally unique id>",
    "status": "inProgress",
    "statusUrl": "<url to status endpoint>",
    "error": {
    // error object in case of an error
    },
    "regionDefinition": "<same as in request>"
}

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

  • matrixId-計算ステータスの追跡やマトリックス結果のダウンロードに使用されるマトリックスの一意の識別子。
  • status-計算のステータス。
  • statusUrl-ステータスをポーリングするURL。
  • error-エラーオブジェクト。通常、リクエストが検証を通過しなかった場合に返されます。
  • regionDefinition-マトリックスの計算に使用されるリージョン定義。ユーザーが指定したもの、または自動的に派生したもの (autoCircleがリクエストされた場合) のいずれかです。

マトリックス計算のステータスをポーリングする

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

> GET <statusUrl>
> Authorization: Bearer <token>
---
< HTTP/1.1 303 See Other
< Content-Type: application/json
< Location: <url to download calculation result>

レスポンスは最初の計算リクエストと同じスキーマです。

{
    "matrixId": "<globally unique id>",
    "status": "completed",
    "resultUrl": "<url to download calculation result>",
    "error": {
        // error object in case of an error
    },
    // same as request
    "regionDefinition": {
        "type": "circle",
        "center": {"lat": 0.0, "lng": 0.0},
        "radius": 10000
    }
}

ステータスコード200、ステータスaccepted、inProgressのいずれかを受信した場合は、計算が完了してHTTPステータスコード303 See Otherが返されるまでポーリングを続行する必要があります。フィールドresultUrlと一致するヘッダーLocationが、マトリックス結果の場所と一緒に追加されます。自動リダイレクトをサポートするクライアントは、マトリックス結果に自動的にリダイレクトされ、S3リソースにリダイレクトされます。

📘

注

APIキー認証のユーザーへの警告：ステータスリクエストから返されたLocationヘッダーのURLにはapiKeyパラメーターが含まれません。リダイレクトを無効にするようにクライアントを設定し、代わりに次のセクションで説明するようにマトリックス結果をダウンロードする必要があります。リクエストにAPIキーのクエリパラメーターを含めるようにします。

マトリックス結果をダウンロードする

マトリックス計算のステータスがcompletedの場合、計算されたマトリックスは、matrixId要素で指定されたIDを使用して利用できます。計算が完了していないマトリックス結果をリクエストすると、HTTPステータスコード404 Not Foundが発生します。

> GET <resultUrl>
> Content-Type: application/json
> Accept-Encoding: gzip

上のリクエストに対するレスポンスは、圧縮された (gzip) JSONドキュメントへのリダイレクトを提供します。リダイレクトはS3リソースへの自己署名URLです。

📘

注

OAuth 2.0認証のユーザーへの警告：一部のクライアントは、リダイレクト後もヘッダーAuthorizationを各リクエストに追加するように設定されています。このようなクライアントは、矛盾する承認方法が原因で自己署名S3URLにアクセスするとエラーが発生します。AuthorizationヘッダーがS3エンドポイントに送信されていないことを確認してください。

マトリックス結果の構造は次のとおりです。

{
    "matrixId": "{matrixId}",
    "matrix": {
        "numOrigins": 10,
        "numDestinations": 1000,
        // 10,000 travel times
        // entry k corresponds to origin i and destination j by the formula:
        // k = num_destinations * i + j
        "travelTimes": [10, 20, 0, ...],
        "errorCodes": [0, 0, 0, ...]   // error for each pair of (origin, dest) if any
    },
    "error" {
        // error object in case of an error
    }
}
📘

注

以前のマトリックス計算の結果はしばらくすると破棄され、今後数時間しか利用できなくなります。

次のステップ

  • 利用可能な例の全リストは、チュートリアルの章を参照してください。
  • このドキュメントをカバーする利用規約については、「HERE Documentation License」(HEREドキュメントのライセンス) を参照してください。

13 日前の更新