Fleet Management

Integrating with HERE Engine

One of the external distance and service engines used in calculating the distance and the service time between locations in Oracle Transportation Management is HERE. HERE captures location content such as road networks, buildings, parks and traffic patterns and licenses that mapping content, along with map-related navigation and location services. It provides location services through REST API including Geo Coding, Search, Maps, Navigation, Routing, Fleet Telematics, and more.

Following are the different use cases supported with integration to HERE:

  • Geo coding: Get latitude/longitude of a location based on an address. The latitude/longitude can be fetched based on different geo hierarchy types.
  • Distance: Calculate the distance between two locations.
  • Service Time: Calculate the time taken to travel between two locations.
  • Custom Routes: HERE provides a service to define your own routes that do not exist or block some roads which the truck should not take. Using this service you can calculate the distance and time between two locations which include these custom routes.
  • Custom Locations: HERE provides a service to define the boundaries of a location (distribution center, warehouse, etc.) and also the access points for the location. Using this service you can calculate the distance and time between two locations which include these custom locations.
  • Generate Rush Hour: Calculate the delta of travel time with and without traffic between locations defined in a region.
  • Weekend Restrictions (using Fleet Telematics): Calculate the distance and the service time including some weekend restrictions and rest times for drivers.

These use cases are supported with the following integrations of Oracle Transportation Management with HERE.

  • HERE: This integration supports all the services that have the output format as XML. This integration supports V6 and V7 HERE routing services. It also supports V6 Geocoding, custom routes, custom locations, and matrix routing services. The authentication for HERE is defined by a property glog.ExternalDistanceEngine.HERE.authenticationType and the possible values are AppIdAppCode, ApiKey, and OAuth. If the option selected is "HERE" (version 7), enter an External System ID.
  • HERE Routing: This integration supports the services that provide distance and service time, and have the output format as only JSON. This integration supports V8 HERE Routing services and can not be used for geocoding, custom routes, custom locations, and matrix routing services. This integration is used for the generation of the rush hour when the glog.business.session.useMatrixServiceToGenerateRushHours is set to false. The authentication used for HERE Routing is OAuth. If the option selected is "HERE - Routing" (version 8) option, enter an External System ID.
  • HERE Geocoding: This integration supports the services that provide Geocoding services and have the output format as only JSON. This integration supports V7 HERE Geocoding services. The authentication used for HERE Geocoding is OAuth.

HERE

This is the initial integration that is provided with HERE services. It is designed for parsing XML output for all the use cases. This integration is available when an EDE/ESE (External Distance Engine or External Service Engine) is defined either with the java class as glog.business.rate.ratedistance.external.HereEngine or with External Engine Type as HERE.

In this integration, the services can be accessible using the URL in the following format: https://<Service End Point>/<resource>/<version>/<operation>.<Output Format>

The <Output Format> used in this case is always XML. So the service URL in this case is always: https://<Service End Point>/<resource>/<version>/<operation>.xml

Seed Data

For this integration, some out-of-box records are provided. Most of the time you can use these out-of-box EDE/ESE for distance and service time calculations. The recommended approach is to copy these EDE/ESE and provide the static parameters for configuring as you see fit to use for different planning purposes.

External Distance Engine

  1. HERE_LATLONG_TO_LATLONG - This is for calculating the distance between two points. Provide this EDE to the rate distance that is to be used in the rate offering/rate record. This EDE is provided with the following parameters:
    1. HOST - here.route.host (property pointing to the service url)
    2. SOURCE_ADDRESS_TYPE - LAT_LONG
    3. DEST_ADDRESS_TYPE - LAT_LONG
    4. ROUTING_MODE_TYPE - fastest
    5. EQUIPMENT_RESTRICTIONS - No
    6. TOLL_PREFERENCE - Normal (value 0)
    7. TRANSPORT_MODE
  2. HERE_ADDRESS -  This is used for geo coding of a location based on the address. The latitude/longitude is fetched based on the address type 'ADDRESS' which fetches the address from the location.
    1. HOST - here.geocode.host (property pointing to the service URL)
    2. SOURCE_ADDRESS_TYPE - ADDRESS

External Service Engine

  1. HERE_LATLONG_TO_LATLONG - This is for calculating the service time or used in generating Rush Hour Data. Provide this ESE to the rate distance that is to be used in the rate offering/rate record. This ESE is provided with the following parameters:
    1. HOST - here.route.host (property pointing to the service URL)
    2. SOURCE_ADDRESS_TYPE - LAT_LONG
    3. DEST_ADDRESS_TYPE - LAT_LONG

Authentication

For this integration, there are three types of authentication:

  1. App Id and App Code
  2. API Key
  3. OAuth

The property glog.ExternalDistanceEngine.HERE.authenticationType, has been added to select one of the authentication type.

This property can have one the following values and these values are case sensitive:

  • AppIdAppCode
  • ApiKey
  • OAuth

The default authentication type is AppIdAppCode to have backward compatibility from the previous releases. However, it is recommended that you use the authentication type as OAuth.

App Id and App Code Authentication (glog.ExternalDistanceEngine.HERE.authenticationType=AppIdAppCode)

The current way of authentication and default for the integration of HERE with Oracle Transportation Management is using an app_id and app_code. HERE will deprecate this authentication as this is less secure and does not have any way of rotating the credentials. HERE will only support this for the existing clients and for all the new clients they would not be providing an app_code. The app_id is, however, created for every client when they register their project with HERE.

The authentication credentials app_id and app_code are provided using the properties here.app_id and here.app_code in Oracle Transportation Management.

In this authentication, the service URL is appended with the query parameters with parameter name as app_id and its value. Similarly, the app_code and its value will be appended. The other parameters are also appended to the service URL to form the query.

https://<Service End Point>/<resource>/<version>/<operation>.xml?app_id=<app_id value>&app_code=<app_code value>&waypoint0=geo!lat,long&waypoint1=geo!lat,long&mode=Type;TransportModes;TrafficMode;Feature

EDE/ESE (External Distance Engine/External Service Time Engine)

Depending on the use case you may have to create an EDE or ESE either with the Java class as glog.business.rate.ratedistance.external.HereEngine or with the External Engine Type as HERE.

The parameters should always have HOST with a property that defines the service URL for the use case.

Use Case - Service URL

The service URLs or the value of the property specified by EDE/ESE parameter HOST which is usually here.route.host for each of the use case are:

  1. Geo coding - https://geocoder.api.here.com/6.2/geocode.xml
  2. Distance - https://route.api.here.com/routing/7.2/calculateroute.xml
  3. Service Time - https://route.api.here.com/routing/7.2/calculateroute.xml
  4. Custom Routes - https://cre.api.here.com/2/calculateroute.xml
  5. Custom Locations - https://cle.api.here.com/2/calculateroute.xml
  6. Generate Rush Hour (Calculating the delta of service time difference with and without traffic for a defined region pairs) - If the property glog.business.session.useMatrixServiceToGenerateRushHours is false, set the property here.route.host to https://route.api.here.com/routing/7.2/calculateroute.xml; and if true, set the property here.route.matrix.host to https://route.api.here.com/routing/7.2/calculatematrix.xml
  7. Weekend Restrictions (Using Fleet Telematics) - https://fleet.api.here.com/2/calculateroute.xml

API Key Authentication (glog.ExternalDistanceEngine.HERE.authenticationType=ApiKey)

HERE recommends to use apiKey that can be generated in the HERE portal for authentication purposes. The apiKey is like a password for the user. You can generate at the most two apiKey at any given time and they can be rotated by deleting one and generating a fresh apiKey. Refer to the section Obtaining API Key or OAuth 2.0 Credentials.

The authentication credential apiKey is provided using the property here.api_key in Oracle Transportation Management.

In this authentication, the service URL is appended with the query parameter with parameter name as apiKey and its value.

https://<Service End Point>/<resource>/<version>/<operation>.xml?apiKey=<apiKey value>&waypoint0=geo!lat,long&waypoint1=geo!lat,long&mode=Type;TransportModes;TrafficMode;Feature

EDE/ESE (External Distance Engine/External Service Time Engine)

Depending on the use case, you may have to create an EDE or ESE either with the Java class as glog.business.rate.ratedistance.external.HereEngine or with the External Engine Type as HERE.

The parameters should always have HOST with a property that defines the service URL for the use case.

Use Case - Service URL

The service URLs or the value of the property specified by EDE/ESE parameter HOST which is usually here.route.host for each of the use case are:

  1. Geo coding - https://geocoder.ls.hereapi.com/6.2/geocode.xml
  2. Distance - https://route.ls.hereapi.com/routing/7.2/calculateroute.xml
  3. Service Time - https://route.ls.hereapi.com/routing/7.2/calculateroute.xml
  4. Custom Routes - https://fleet.ls.hereapi.com/2/calculateroute.xml
  5. Custom Locations - https://fleet.ls.hereapi.com/2/calculateroute.xml
  6. Generate Rush Hour (Calculating the delta of service time difference with and without traffic for a defined region pairs) - If the property glog.business.session.useMatrixServiceToGenerateRushHours is false, set the property here.route.host to https://route.ls.hereapi.com/routing/7.2/calculateroute.xml; and if true, set the property here.route.matrix.host to https://matrix.route.ls.hereapi.com/routing/7.2/calculatematrix.xml
  7. Weekend Restrictions (Using Fleet Telematics) - https://fleet.ls.hereapi.com/2/calculateroute.xml

For more information about the changes in the host for service URLs, refer to HERE Developer Domain names for HERE services. 

OAuth 2.0 Authentication (glog.ExternalDistanceEngine.HERE.authenticationType=OAuth)

OAuth based authentication  authenticates the request by posting an access token in the request to HERE. Obtain the access token using a separate authentication service endpoint. This endpoint will ask for an OAuth1 based signature to identify a consumer key and the secret. Refer to the section Obtaining API Key or OAuth 2.0 Credentials for obtaining the necessary credentials required for OAuth.

In this authentication, we do not pass the required authentication as a query parameter. Instead a request is posted using a bearer access token that is obtained by using an Authorization Service URL. 

https://<Service End Point>/<resource>/<version>/<operation>.xml?waypoint0=geo!lat,long&waypoint1=geo!lat,long&mode=Type;TransportModes;TrafficMode;Feature

The Service URL, Authorization Service URL, Consumer Key, and Consumer Secret are specified by using an external system. The operation in the above-mentioned URL is passed from the code according to the use case and need not be defined in the external system URL.

Define an external system with the following details:

  1. Provide the Authentication Type as OAuth 2.0 - Client Credentials.
  2. Provide the Authorization Service Authentication Type as OAuth 1.0 Signature.
  3. Provide the Consumer Key and Consumer Secret as the value of the key here.access.key.id and here.access.key.secret respectively from credential.properties generated for HERE.
  4. Provide the Signature Algorithm as HMAC-SHA256.
  5. Provide the Authorization Service URL as https://account.api.here.com/oauth2/token
  6. Provide the URL based on UseCase - ServiceURL section defined below.
  7. Provide the Content Type as text/xml or application/xml.
EDE/ESE (External Distance Engine/External Service Time Engine)

Depending on the use case, you may have to create an EDE or ESE either with the Java class as glog.business.rate.ratedistance.external.HereEngine or with the External Engine Type as HERE.

The External System field will be displayed on the EDE/ESE only when the authentication type is OAuth.

Use Case - Service URL

The URLs for each of the use case are:

  1. Geo coding - https://geocoder.ls.hereapi.com/6.2/
  2. Distance - https://route.ls.hereapi.com/routing/7.2/
  3. Service Time - https://route.ls.hereapi.com/routing/7.2/
  4. Custom Routes - https://fleet.ls.hereapi.com/2/
  5. Custom Locations - https://fleet.ls.hereapi.com/2/
  6. Generate Rush Hour (Calculating the delta of service time difference with and without traffic for a defined region pairs) - If the property glog.business.session.useMatrixServiceToGenerateRushHours is false, use an external system with URL as https://route.ls.hereapi.com/routing/7.2/; and if true, use an external system with URL as https://matrix.route.ls.hereapi.com/routing/7.2/
  7. Weekend Restrictions (Using Fleet Telematics) - https://fleet.ls.hereapi.com/2/

For more information about the changes in the host for service URLs, refer to HERE Developer Domain names for HERE services. 

HERE Routing

This is designed for parsing JSON output for all the use cases. This integration is available when an External Distance Engine or External Service Engine is defined either with the Java class as glog.business.rate.ratedistance.external.HereRouting or with the External Engine Type as HERE - Routing.

In this integration, the services can be accessed using the URL in the following format: https://<Service End Point>/<version>/<resource>

Seed Data

For this integration, few out-of-box records are provided. Use these out-of-box EDE/ESE as a template and create your own record for distance, service time calculation, and to Generate Rush Hour data. The recommended approach is to copy these EDE/ESE and provide the static parameters for configuring as you see fit to use for different purposes.

For Generate Rush Hour (Calculating the delta of service time difference with and without traffic for a defined region pairs), if the property glog.business.session.useMatrixServiceToGenerateRushHours is false, then the out-of-box ESE provided will be used to calculate the Rush Hour data. If it is true, then it uses a variation of HERE - Routing that uses matrix service rather than the routing service. 

External System

There are two external systems as described below:

  1. The external system HERE_ROUTING_SAMPLE_ES is provided as an example used for EDE/ESE - HERE_ROUTING_LATLONG_TO_LATLONG. This External System is configured with the following fields:
    1. Authentication Type - OAuth 2.0 - Client Credentials.
    2. Authorization Service Authentication Type - OAuth 1.0 Signature.
    3. Signature Algorithm - HMAC-SHA256.
    4. Authorization Service URL as https://account.api.here.com/oauth2/token
    5. URL -https://router.hereapi.com/v8/
    6. Content Type - application/json
  2. The external system HERE_ROUTING_MATRIX_SAMPLE_ES is provided as an example used only for ESE -HERE_ROUTING_MATRIX_LATLONG_TO_LATLONG. This External System is configured with the following fields:
    1. Authentication Type - OAuth 2.0 - Client Credentials.
    2. Authorization Service Authentication Type - OAuth 1.0 Signature.
    3. Signature Algorithm - HMAC-SHA256.
    4. Authorization Service URL as https://account.api.here.com/oauth2/token
    5. URL - https://matrix.router.hereapi.com/v8/
    6. Content Type - application/json

You will have to provide the Consumer Key and Consumer Secret obtained from HERE.

External Service Engine

  1. HERE_ROUTING_LATLONG_TO_LATLONG - This is for calculating the service time or used in generating Rush Hour Data. Provide this ESE to the rate distance that is to be used in the rate offering/rate record. This ESE is provided with the following parameters:
    1. SOURCE_ADDRESS_TYPE - LAT_LONG
    2. DEST_ADDRESS_TYPE - LAT_LONG
  2. HERE_ROUTING_MATRIX_LATLONG_TO_LATLONG - This is for calculating the transit time delay in the rush hour process. Provide this ESE in the dropdown to be used for generating the rush hour data from Contract and Rate Management>Process Management when glog.business.session.useMatrixServiceToGenerateRushHours is true. The ESE is provided with External System HERE_ROUTING_MATRIX_SAMPLE_ES. The ESE is provided with the following parameters:
    1. SOURCE_ADDRESS_TYPE - LAT_LONG
    2. DEST_ADDRESS_TYPE - LAT_LONG

External Distance Engine

  1. HERE_ROUTING_LATLONG_TO_LATLONG - This is for calculating the distance between two points. Provide this EDE to the rate distance that is to be used in the rate offering/rate record.
    1. This EDE is provided with External System HERE_ROUTING_SAMPLE_ES.
    2. This EDE is provided with the following parameters:
      1. SOURCE_ADDRESS_TYPE - LAT_LONG
      2. DEST_ADDRESS_TYPE - LAT_LONG

Authentication

For this integration, only OAuth authentication is supported. No property is required.

OAuth based authentication  authenticates the request by posting an access token in the request to HERE. Obtain the access token using a separate authentication service endpoint. This endpoint will ask for an OAuth1 based signature to identify a consumer key and the secret. Refer to the section Obtaining API Key or OAuth 2.0 Credentials for obtaining the necessary credentials required for OAuth.

In this authentication, we do not pass the required authentication as a query parameter. Instead a request is posted using a bearer access token that is obtained by using an Authorization Service URL. 

https://<Service End Point>/<version>/<resource>?origin=lat,long&destination=lat,long&routingMode=Type&transportMode=TransportMode&avoid[features]=CommaSeparatedFeaturesToAvoid&truck[truckParameterType]=truckParameterValue

The Service URL, Authorization Service URL, Consumer Key, and Consumer Secret are specified by using an external system. The operation in the above-mentioned URL is passed from the code according to the use case and need not be defined in the external system URL.

Define an external system with the following details:

  1. Provide the Authentication Type as OAuth 2.0 - Client Credentials.
  2. Provide the Authorization Service Authentication Type as OAuth 1.0 Signature.
  3. Provide the Consumer Key and Consumer Secret as the value of the key here.access.key.id and here.access.key.secret respectively from credential.properties generated for HERE.
  4. Provide the Signature Algorithm as HMAC-SHA256.
  5. Provide the Authorization Service URL as https://account.api.here.com/oauth2/token
  6. Provide the URL value based on Use Case - ServiceURL section defined below.
  7. Provide the Content Type as application/json.

EDE/ESE (External Distance Engine/External Service Time Engine)

Depending on the use case, you may have to create an EDE or ESE either with the Java class as glog.business.rate.ratedistance.external.HereRouting or with the External Engine Type as HERE - Routing.

When you select the External Engine Type as HERE - Routing, the External System field will be displayed. Define the external system as described above and provide it here.

Use Case - Service URL

The URLs for each of the use case are:

  1. Distance - https://router.hereapi.com/v8/routes
  2. Service Time - https://router.hereapi.com/v8/routes
  3. Generate Rush Hour - if the property glog.business.session.useMatrixServiceToGenerateRushHours is false, then set glog.ExternalDistanceEngine.HERE.authenticationType to OAuth and  set the endpoint URL in the corresponding External System of ESE to https://router.hereapi.com/v8/routes. If the property is true, then set to https://matrix.router.hereapi.com/v8

For more information on the changes in the host for service URLs, refer to HERE Developer Domain names for HERE services. 

HERE Geocoding

This is the latest integration for Geocoding that is provided with HERE services. It is designed for parsing JSON output for all the use cases. This integration is available when an External Distance Engine or External Service Engine is defined either with the Java class as glog.business.rate.ratedistance.external.HereGeocoding or with the External Engine Type as HERE - Geocoding.

The HERE Geocoding and Search API v7 support two types of queries:

  • Qualified (structured): This is a structured and hybrid query. This format of query is used when the EDE parameter  SOURCE_ADDRESS_TYPE is one of the following: CITY_COUNTRY, CITY_POSTAL, CITY_PROVINCE, POSTAL_CODE, POSTAL_CODE_COUNTRY, POSTAL_CODE_PROVINCE, STREET_ADDRESS.
  • Free form: General address. The geocode endpoint enables the entry of unstructured character strings as queries like addresses or places. This format of query is used when the EDE parameter  SOURCE_ADDRESS_TYPE is ADDRESS.

For example, a query for "125 Beacon Street, Boston, MA, USA" can be expressed in multiple ways as follows:

  • Freeform: "125 Beacon Street, Boston, MA, USA"
  • Qualified: houseNumber=125;street=Beacon Street;city=Boston;state=MA;country=USA

External System

An External System must be configured with the following fields:

  1. Authentication Type - OAuth 2.0 - Client Credentials.
  2. Authorization Service Authentication Type - OAuth 1.0 Signature.
  3. Signature Algorithm - HMAC-SHA256.
  4. Authorization Service URL as https://account.api.here.com/oauth2/token
  5. URL - https://geocode.search.hereapi.com/v1
  6. Content Type - application/json

You will have to provide the Consumer Key and Consumer Secret obtained from HERE.

External Distance Engine

The HERE Geocoding is used to validate an address. Define an EDE that has a parameter SOURCE_ADDRESS_TYPE having one of the following values:

  • Address (Address Validation Only)
  • City Country (Address Validation Only)
  • City Postal (Address Validation Only)
  • City Province (Address Validation Only)
  • Postal Code (Address Validation Only)
  • Postal Code Country (Address Validation Only)
  • Postal Code Province (Address Validation Only)
  • Street Address (Address Validation Only)

Seed Data

For this integration, some out-of-box records are provided. Use these out-of-box EDE as a template and create your own record to validate an address. The recommended approach is to copy these EDE and provide the static parameters for configuring as you see fit to use for different planning purposes.

External Distance Engine

HERE_GEOCODING - This is for validating an address. Provide this EDE to validate the address using Validate Address web action or Validate Location Address agent action for a Location. This EDE is provided with the external system, HERE_GEOCODING_SAMPLE_ES. This EDE is provided with the below parameter:

  • SOURCE_ADDRESS_TYPE - ADDRESS

Authentication

For this integration, only OAuth authentication is supported. No property is required.

OAuth based authentication authenticates the request by posting an access token in the request to HERE. Obtain the access token using a separate authentication service endpoint. This endpoint will ask for an OAuth1 based signature to identify a consumer key and the secret. Refer to the section Obtaining API Key or OAuth 2.0 Credentials for obtaining the necessary credentials required for OAuth.

In this authentication, we don't pass the required authentication as a query parameter. Instead, a request is posted using a bearer access token that is obtained by using an Authorization Service URL. 

https://<Service End Point>/<version>/<resource>?q=FreeFormQuery&qq=SemiColonSeparatedQualifiedQuerySubParameters

The Service URL, Authorization Service URL, Consumer Key, and Consumer Secret are specified by using an external system. The operation in the above-mentioned URL is passed from the code according to the use case and need not be defined in the external system URL.

Define an external system with the following details:

  1. Provide the Authentication Type as OAuth 2.0 - Client Credentials.
  2. Provide the Authorization Service Authentication Type as OAuth 1.0 Signature.
  3. Provide the Consumer Key and Consumer Secret as the value of the key here.access.key.id and here.access.key.secret respectively from credential.properties generated for HERE.
  4. Provide the Signature Algorithm as HMAC-SHA256.
  5. Provide the Authorization Service URL as https://account.api.here.com/oauth2/token
  6. Provide the URL value based on the Use Case - ServiceURL section defined below.
  7. Provide the Content Type as application/json.

EDE (External Distance Engine)

Depending on the use case, you may have to create an EDE either with the Java class as glog.business.rate.ratedistance.external.HereGeocoding or with the External Engine Type as HERE - Geocoding.

When you select the External Engine Type as HERE - Geocoding, the External System field will be displayed. Define the external system as described above and provide it here.

Use Case - Service URL

The use case for the Here Geocoding is to validate an address and the URL is https://geocode.search.hereapi.com/v1.

For more information on changes in the host for service URLs, refer to HERE Developer Domain names for HERE services.

Obtaining API Key or OAuth 2.0 Credentials

You need to register in the HERE development portal and create a project. The project is provided with an App ID. For this one you can generate the API Key and also create the OAuth credentials. You can create an account by registering at the HERE Developer site.

Use Create API Key under REST section for creating an API Key. For more details, see HERE Developer API Keys.

Use Create Credentials under REST section for creating credentials required for OAuth 2.0. For more details, see HERE Developer OAUTH Tokens.

Related Topics

External Distance/Service Engine and Map Parameters

glog.ExternalDistanceEngine Properties

HERE Properties

External System

External Distance Engine

External Service Engine

Copyright © 2001, 2023, Oracle and/or its affiliates.

For the latest installation and reference guides, go to the online library. For the additional materials, see Knowledge Document 796594.1 on My Oracle Support.

For questions about Oracle Transportation Management or Global Trade Management, contact Support or find the Support phone number for your region.

If you have any questions or comments about this documentation page, please Contact Oracle Documentation. Was this page helpful? Click to send feedback.How can we improve this page?What did you like about this page?Comments