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.
• Generate Rush Hour: Calculate the delta of travel time with and without traffic between locations defined in a region.

These use cases are supported with the following integrations of Oracle Transportation Management with HERE. The use cases refer to content on the External Distance Engine page.

• HERE: This integration supports all the services that have the output format as XML. 
• 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 on the External Distance Engine page.
• 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:
   • HOST: here.route.host (property pointing to the service URL)
   • SOURCE_ADDRESS_TYPE: LAT_LONG
   • DEST_ADDRESS_TYPE: LAT_LONG
   • ROUTING_MODE_TYPE: fastest
   • EQUIPMENT_RESTRICTIONS: No
   • TOLL_PREFERENCE: Normal (value 0)
   • 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.
   • HOST: here.geocode.host (property pointing to the service URL)
   • 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:
   • HOST: here.route.host (property pointing to the service URL)
   • SOURCE_ADDRESS_TYPE: LAT_LONG
   • DEST_ADDRESS_TYPE: LAT_LONG

OAuth 2.0 Authentication

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 HERE 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.

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:
   • Authentication Type: OAuth 2.0 - Client Credentials.
   • Authorization Service Authentication Type: HERE OAuth 1.0 Signature.
   • Signature Algorithm: HMAC-SHA256.
   • Authorization Service URL: https://account.api.here.com/oauth2/token
   • URL: https://router.hereapi.com/v8/
   • 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:
   • Authentication Type: OAuth 2.0 - Client Credentials.
   • Authorization Service Authentication Type: HERE OAuth 1.0 Signature.
   • Signature Algorithm: HMAC-SHA256.
   • Authorization Service URL: https://account.api.here.com/oauth2/token
   • URL: https://matrix.router.hereapi.com/v8/
   • 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:
   • SOURCE_ADDRESS_TYPE: LAT_LONG
   • 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 drop-down 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:
   • SOURCE_ADDRESS_TYPE: LAT_LONG
   • 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:
      • SOURCE_ADDRESS_TYPE: LAT_LONG
      • 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 HERE 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:

• Distance: https://router.hereapi.com/v8/routes.
• Service Time: https://router.hereapi.com/v8/routes.
• 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:

• Authentication Type: OAuth 2.0 - Client Credentials.
• Authorization Service Authentication Type: HERE OAuth 1.0 Signature.
• Signature Algorithm: HMAC-SHA256.
• Authorization Service URL: https://account.api.here.com/oauth2/token.
• URL: https://geocode.search.hereapi.com/v1.
• 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 HERE 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 OAuth 2.0 Credentials

You need to register in the HERE development portal and create a project. Use Create Credentials under REST section for creating credentials required for OAuth 2.0. For more details, see HERE Developer OAUTH Tokens.