利用開始

このセクションでは、 HERE platform のMatrix Routingサービスを使用し実行する方法について説明します。

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

注

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

HERE アカウントの取得

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

APIキーを取得

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

HERE アカウントを使用して HERE platform にサインイン。
ランチャから Access Manager を開きます。
[ アプリ ] タブを選択します。
[ 新しいアプリを登録] をクリックします。
アプリの名前を入力します。
プロジェクトへの既定のアクセス権で、[プロジェクトなし] を選択します。
[ 登録] をクリックします

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

HERE アカウントを使用して HERE platform にサインイン。
ランチャから Access Manager を開きます。
[ アプリ ] タブを選択します。
[ アプリ ] タブの一覧でアプリ名をクリックして、アプリを開きます。
資格情報タブを選択します。
API Keys をクリックします。
[Create API キー( 新規作成 )] をクリックし

リクエストの送信

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

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

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

同期リクエスト

同期 API を使用すると、マトリックス計算リクエストをサーバーに送信し、応答を待機することになります。同期リクエストには、マトリックスのディメンションにさらに制限があります。

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

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

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

注

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

詳細については、『 Identity & Access Management Guide 』を参照してください。

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
    }
}

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

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

非同期リクエスト

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

マトリックス計算リクエスト。
計算ステータスをポーリングしています。
マトリックス結果をダウンロードしています。

マトリックスの計算を要求します

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

注

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

詳細については、『 Identity & Access Management Guide 』を参照してください。

> 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を各要求に追加するように設定されています。このようなクライアントは、矛盾する承認方法が原因で自己署名 S3 URL にアクセスするとエラーが発生します。 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 アカウントの取得

APIキーを取得

リクエストの送信

同期リクエスト

注

非同期リクエスト

マトリックスの計算を要求します

注

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

API キー認証のユーザーに対する警告です

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

OAuth 2.0 認証のユーザーに対する警告です

注

次のステップ

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

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

開発者

利用開始

注

HERE アカウントの取得

APIキーを取得

リクエストの送信

同期リクエスト

注

非同期リクエスト

マトリックスの計算を要求します

注

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

API キー 認証のユーザーに対する警告です

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

OAuth 2.0 認証のユーザーに対する警告です

注

次のステップ

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

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

開発者

API キー認証のユーザーに対する警告です

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