HERE Matrix Routing API v8の違反マッピング

違反マッピングにより、マトリックス計算で検出された違反に関するより詳細で関連性の高い情報を取得できます。

これは、特定の違反タイプをユーザー指定のカテゴリー (1または2) にマッピングすることで実現されます。

マッピングされた違反は、デフォルトではすべての違反が報告されるエラーコード3で報告される代わりに、定義されたカテゴリーにグループ化されます。

ユースケースの例：

宅配業者は、配送先が車でアクセス可能か、または車両規制や一般的な通行止めによりアクセスが遮断されているかを知りたいと考えています。この情報にアクセスすることで、宅配業者は配送先の住所まで車で行くか、徒歩で荷物を配送するかを決定できます。
トラックの運行管理担当は、ディーゼルエンジンが禁止されている地域にガソリンエンジントラックを割り当てたいと考えています。このような場合、禁止領域はリクエスト内でavoid区域として指定され、このavoidルール違反は別のカテゴリーにマッピングされます。これにより、ディーゼル車禁止区域を通過するルートを検知し、ガソリン駆動のトラックに割り当てることができます。

違反のエラーコード

計算されたルートのいずれかが違反となる場合、レスポンスにはerrorCodesの配列が含まれます。これには、出発地と目的地のペアごとに1つのエラーコードが含まれます。

エラーコードは次のように決定されます。

エラーコード	説明
0	計算に成功。違反は見つかりませんでした。
3	ルートは違反を伴って計算されます。違反はどのカテゴリーにもマッピングされません。
5	カテゴリー`1`にマッピングされた違反を少なくとも1件検出しました。
6	カテゴリー`2`にマッピングされた違反を少なくとも1件検出しました。
7	カテゴリーにマッピングされていない違反が少なくとも1件見つかりました。また、カテゴリー`1`に少なくとも1件の違反がマッピングされています。
8	カテゴリーにマッピングされていない違反が少なくとも1件見つかりました。また、カテゴリー`2`に少なくとも1件の違反がマッピングされています。
9	カテゴリー`1`および`2`の両方にマッピングされた違反が少なくとも1件見つかりました。
10	カテゴリーにマッピングされていない違反が少なくとも1件見つかりました。また、カテゴリー`1`および`2`の両方に少なくとも1件の違反がマッピングされています。

構造

違反マッピングを指定するには、violationMappingリクエストパラメーターを使用します。マッピングは、マッピングアイテムの配列で構成されます。

各マッピング項目は、次の2つの側面を指定します：マッピングされる制限、およびそれらがマッピングされるカテゴリー。

違反マッピング項目には3つのタイプがあり、それぞれに設定可能なプロパティがあります。

restriction：truck移動モードのみサポートされます。
traffic：carとtruckの移動モードがサポートされます。
avoidAreasAndSegments：carとtruckの移動モードがサポートされます。

📘
注
現在、違反マッピングはtruckおよびcarの移動モードのみサポートされます。

制限

type: restrictionを使用して、制限違反をマッピングします。

サポートされている制限は次のとおりです。

grossWeight
currentWeight
height

違反のマッピング時は、サポートされている3タイプの制限のみが考慮されることに注意してください。

📘
注
追加の制限タイプのサポートが必要な場合は、サポートリクエストを提出してください。

シンプルな制限マッピング

シンプルな制限マッピングを作成するには、単一の制限タイプを選択し、その値をincludeに設定します。

この例では、grossWeightの制限の違反をカテゴリー1にマッピングします。

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "include"
	}
]

マッピング例の結果として、違反した制限がユーザー指定のカテゴリーにマッピングされるためにはgrossWeight条件を含む必要があります。

その他の違反はマッピングされません。

複数の制限タイプをマッピングする

複数の制限タイプを単一のマッピング項目内のユーザー指定カテゴリーにマッピングするには、値をignoreに設定します。

プロパティに値ignoreを割り当てる場合、制限が違反された場合に関連する条件を含めてもよいが、必ずしも含める必要はないことを意味します。

その結果、指定された制限のいずれかに違反すると、その違反はユーザー指定のカテゴリーにマッピングされます。

この例は、grossWeight制限またはcurrentWeight制限をカテゴリー1にマッピングします。

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "ignore",
		"currentWeight": "ignore"
	}
]

制限タイプごとに2つの個別のマッピング項目を作成することで、同じ結果を得ることができます。

両方の項目でinclude値を使用する必要があります。

次の例を参照してください。

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "include"
	},
	{
		"category": 1,
		"type": "restriction",
		"currentWeight": "include"
	}
]

ignore値を使用する単一のマッピング項目を含む例と、include値を使用する2つのマッピング項目を含む例は、機能的に同等です。

📘
注
2つの制限タイプにマッピングを作成し、両方にincludeの値を設定した場合、両方の制限が同時に違反された場合にのみマッピングが有効になります。いずれか1つが違反しても、マッピングは有効になりません。これを最初の例に適用すると、grossWeight条件とcurrentWeight条件を同時に満たす制限は存在しません。両方の条件にincludeの値を設定すると、これらの違反はユーザー定義カテゴリーにマッピングされることはありません。

その他の制限条件

制限マッピング項目では、次の追加条件を使用できます。

timeDependent：制限に時間依存性があります。
bridge：制限が橋梁にあります。

これらの条件は制限タイプ自体ではありませんが、違反をさらに絞り込むために使用できます。

デフォルトでは、追加の条件に値ignoreが割り当てられます。そのため、マッピング対象となる違反を決定する際には考慮されません。

条件を要求するには値include、条件を禁止するには値excludeを使用します。

この例では、grossWeight違反またはcurrentWeight違反をカテゴリー1にマッピングしますが、それらが橋梁で発生した場合に限られます。

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "ignore",
		"currentWeight": "ignore",
		"bridge": "include"
	}
]

📘
注
橋梁で発生するほとんどの制限は、その長さを超えても適用されます。つまり、橋梁で違反が発生した場合は検出可能ですが、クライアントはこの同じルート上には橋梁以外でも違反が含まれていることを想定する必要があります。

この例では、grossWeight違反をカテゴリー1にマッピングしますが、それが時間依存でない場合に限ります。

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "include",
		"timeDependent": "exclude"
	}
]

トラフィック

道路閉鎖違反をマッピングするには、type: trafficを使用します。

この例では、このような違反はカテゴリー1にマッピングされます。

[
	{
		"category": 1,
		"type": "traffic"
	}
]

その他の制限条件

トラフィックマッピング項目では、次の追加条件を使用できます。

bridge：制限が橋梁にあります。

この例では、橋梁上で発生しない限り、すべてのtraffic違反はカテゴリー1にマッピングされます。

橋梁上で交通違反が検出されると、マッピングが解除され、コード3エラーが発生します。

{
	"category": 1,
	"type": "traffic",
	"bridge": "exclude"
}

エリアとセグメントを回避する

type: avoidAreasAndSegmentsを使用して、avoid[areas]またはavoid[segments]の違反をマッピングします。

この例では、このような違反はカテゴリー2にマッピングされます。

[
	{
		"category": 2,
		"type": "avoidAreasAndSegments"
	}
]

個別のカテゴリーにマッピングする

violationMapping配列の各項目は、違反をユーザー指定のカテゴリーのいずれかにマッピングできます。

違反が配列内の複数の項目に一致する場合、一致した各項目に対して指定されたカテゴリーにマッピングされます。

この例の内容は以下のとおりです。

橋梁上で発生するgrossWeight違反はカテゴリー1にマッピングされます。
橋梁上で発生しないgrossWeight違反はカテゴリー2にマッピングされます。
すべての交通違反もカテゴリー2にマッピングされます。

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "include",
		"bridge": "include"
	},
	{
		"category": 2,
		"type": "restriction",
		"grossWeight": "include",
		"bridge": "exclude"
	},
	{
		"category": 2,
		"type": "traffic"
	}
]