Configure distance provider parameters

Once your tenant is integrated with a distance provider, users with Admin-level permissions and above can configure and save your distance provider parameters within your tenant or your customer’s profile settings. That way, your mileage calculations will match and reconcile according to your customer’s mileage calculation requirements.

Note: Your tenant must be integrated with your distance provider prior to configuring your tenant-level or customer account-level parameters. PC Miler is the only external provider available for truckload (TL), less-than-truckload (LTL), and drayage shipments at this time. If you have a request to integrate with a different distance provider or would like to integrate your tenant with PC Miler, reach out to your Turvo representative.

In this article, you will learn more about:

• How distance provider rules work
• How to integrate a distance provider with your tenant
• How to configure tenant-level distance provider rules
• How to configure customer account-level distance provider rules
• Updating the distance provider for a contract’s lane rate

How distance provider rules work

Enabling distance provider parameters will override Turvo’s default mileage calculator and enable your version of PC Miler as the mileage calculator for applicable shipments. If you do not input parameters, the distance provider will default to the Turvo mileage calculator. 

Your preferred distance provider configuration can be done at the tenant-level, customer account-level, or contract-level. 

• Tenant-level configurations are used when calculating distance for all shipments that the configuration applies to, unless the shipment is rated with a contract and the shipment’s customer has an account-level configuration with different rules.
• Customer account-level configurations are applied to contract lane rates for all of that customer’s shipments that match the configuration’s mode. 
  • If the shipment is not using a customer contract lane rate, and if a tenant-level distance provider configuration applies to the shipment, the tenant-level configuration is used.
• Contract-level configurations are specific to lane rates on that contract. 
  • Lane rates added to customer contracts are locked to using the applicable customer-level configuration. 
  • If no customer account-level configuration is applied and a lane rate is used, the distance provider configuration fields for the lane rate are locked. The tenant-level configuration is used, if applicable to the shipment.
  • Carrier contract lane rates are not locked. They can utilize PC Miler or the default Turvo distance provider. There is no carrier account-level configuration.

Note: If the rules for one level match the one above it, then no recalculation is done.

For example, when a TL shipment is created:

• If: 
  • The tenant-level configuration for TL shipments uses Turvo’s default distance provider; 
  • And the customer’s account has a configuration to use PC Miler for TL shipments; 
  • And the customer’s cost for the shipment is rated using a contracted lane rate;
• Then: 
  • The customer’s account-level configuration for PC Miler is used for that shipment. 

If the customer’s account was not configured with rules for TL shipments or the shipment was not rated via the customer’s contracted lane rate, the tenant-level configuration will apply.

How it impacts shipment information

Using an external distance provider can impact your shipment information in the following ways.

Sharing with partner tenants

The distance calculations created by an external distance provider (e.g., PC Miler) on your tenant can be shared to your partners’ tenants if that partner tenant is not using an external distance provider configuration that would conflict with your own. 

For example, if you are a logistics service provider, when sharing a shipment to your customer’s tenant:

• If your tenant uses PC Miler as a distance provider but your customer’s tenant uses the default Turvo distance provider then the PC Miler-calculated distance from your tenant will appear on the shipment in your customer’s tenant. 
• However, if both your tenant and your customer’s tenant each use a PC Miler configuration that applies to the shipment, then the distance calculated for the shipment in each tenant will utilize that tenant’s own configuration. 

Updating shipments

If a shipment is updated in such a way that it falls under a different distance provider rule than it did before, then Turvo will recalculate the distance and update the shipment.

Impact on ETAs and drive time

ETA and drive time calculation is not affected by your distance provider settings. 

How to integrate a distance provider with your tenant

Users with Owner, Admin, or Super Admin roles in your tenant, can configure an external distance provider for shipments. Additionally, upon shipment creation, these same user roles can set rules for which shipments the provider will use to calculate mileage. Instructions are provided in the sections below.

1. From anywhere in Turvo, click your profile icon in the top right corner.
2. Select Admin console from the drop-down.

3. Click the Settings card to open the tenant settings.

4. Click the Shipments section header, then click Distance Provider. 
   1. The Distance Provider section contains two options, a PC Miler toggle and an API key field.
   2. Note: PC Miler is the only external distance provider available for tenant integration at this time.
5. Click the PC Miler toggle to activate the distance provider settings. 
   1. Note: This will cause additional fields to appear below. These fields will be used to configure rules for distance providers on your tenant, as described in the next section of this article, and are not necessary to complete these steps.

6. You will need to obtain an API Key from your PC Miler account to input into the API Key field.
7. Click SAVE to complete the integration. 

How to configure tenant-level distance provider rules

Once a distance provider has been integrated, as demonstrated in the section above, you can configure rules for which providers are used for shipments on your tenant, depending on the shipments’ mode. The following steps detail how the providers can be applied to shipments:

1. Click Add provider to create a rule for how your provider(s) will be applied to shipments.
   1. If no rules have been created, use the empty fields that appeared when you clicked the PC Miler toggle, as seen in the section above.
2. Use the Mode drop-down to select the type of shipment the rule will apply to.
   1. Note: The PC Miler integration is available for the TL, LTL, and Drayage modes only. All other modes must use Turvo’s default distance provider.
3. Use the Provider drop-down to select which provider will be used for the shipments of the selected mode. 
   1. Select PC Miler to use your integration or select Turvo to use the default distance provider.
4. Use the Applicable for drop-down to select the shipments that the rule should apply to:
   1. Owned shipments: The selected distance provider will only be used for the shipments created within your tenant that match the selected mode. 
      1. Note: All shipments that are shared to your tenant from a shipping partner’s tenant will use that tenant’s distance provider.
   2. All shipments: The selected distance provider will be used for shipments that match the selected mode, whether they are created within your tenant or shared to your tenant by a shipping provider.
      1. Note: If the shipment is shared to your tenant and the original tenant uses a different distance provider than yours, then the distance is recalculated for your tenant.

5. If the Provider is set to PC Miler, click Show more details to input additional information to configure your route preferences. While these fields are optional, we always recommend providing as many details as possible for the most complete picture of your distance provider. These fields are not available when selecting Turvo as the provider.
   1. Version: Use the drop-down to select your version of PC Miler. 
      1. Note: Selecting Current will default to the latest version of PC Miler. This should update roughly every 15 days.
   2. Route Type: Use the drop-down to choose your preferred route type. Select from Practical (Default), Shortest, or Fastest.
   3. Use Highways only: Click this checkbox to indicate that the route should prioritize highways.
   4. Borders only: Click this checkbox to indicate that international border crossings are allowed where convenient. Leaving it unchecked will minimize the number of border crossings in the route as much as possible.
   5. Toll roads: Use the drop-down to configure how toll roads should be used in the route. Select from Always avoid, Avoid if possible, or Use.
   6. Toll discount: Use the drop-down to select from applicable toll discount programs, such as EZPass. Select all that apply.
   7. Include ferry distances in mileage calculation: Click this checkbox to indicate that the distance covered while the vehicle is on a ferry should be included in the distance calculation.
   8. Vehicle profile: Use this drop-down to select the type of vehicle profile that the mileage calculation should consider. This is useful for finding appropriate routes when the size restrictions of roads and underpasses may be an issue. 
   9. Class override: Use this drop-down to select the type of vehicle class that size and weight restrictions should be overridden for when calculating the distance. 
   10. Restrict override: Click this checkbox to indicate that size and weight restrictions pertaining to the selection in Vehicle profile should be overridden when calculating the distance.
6. You may create additional rules by clicking +Add provider. 
   1. Note: Only one rule can be made for each mode.
7. When you are finished, click SAVE to apply the changes to your tenant.

Once applied, the selected distance provider will calculate distance based on the parameters set for each mode’s rule. If a shipment is created that a rule does not apply to, that shipment will use the default Turvo distance provider.

How to configure customer account-level distance provider rules

You can also configure a specific distance provider for a specific customer. These configurations are only applied to shipments for that customer that utilize contracted lane rates. Shipments that are not rated via lane rates for that customer will use the tenant-level settings.

1. Navigate to the customer’s profile using Accounts > Customer in the left navigation bar or by searching for the customer using the global search bar.

2. Once inside of the customer’s profile, click on the Details tab and scroll down to Settings.

3. Click the Settings segment to expand it, then click Distance provider.

4. To add a distance provider, click + Add distance provider.

5. Select the Mode and Provider from the available options in the drop-down menu.

6. Depending on the Mode and Provider selected, additional optional fields may appear that allow you to configure your route preferences. While these fields are optional, we always recommend providing as many details as possible for the most complete picture of your distance provider.  The additional fields match the fields used in the tenant-level rules, as described in the previous section.
   1. Note: PC Miler is the only external distance provider available.

7. When you’ve entered all of the necessary information, click SAVE to save your changes.

These customer account-level rules will now be utilized to calculate routes for contracted lane rates on this customer’s shipments.

Updating the distance provider for a contract’s lane rate

See our article, How to add a lane rate to contracts or global rates, for more information on applying a distance provider to a lane rate. 

While updating customer contract lane rates, the distance provider fields are locked. The lane rate will utilize the customer account-level distance provider configuration, or they will be blank if no configuration is applied. If blank, the shipment will use the tenant-level distance provider configuration.

While updating carrier contract lane rates, PC Miler or Turvo’s default distance provider can be applied to the lane rate, regardless of the configurations detail

Note: External distance providers must be configured in your tenant, as seen in the How to integrate a distance provider with your tenant section above, before they can be applied to lane rates.