Rate Distance in OTM is the calculated distance between a shipment’s origin and destination. OTM needs this distance to cost TL shipments on per-mile rate contracts. There are two ways to provide this distance:
- Distance Lookup — your team pre-loads a table of distances lane by lane. OTM looks up the matching lane and reads the stored mileage. No external system is needed.
- External Distance Engine — OTM calls a third-party routing engine (such as PCMiler from ALK Technologies) at plan time to fetch the live calculated distance. This requires a license and API access to the external system.
The Rate Distance record is linked to the Rate Offering (carrier contract) — whichever approach you configure, you reference it in that field so OTM knows which distance method to use when costing shipments under that contract.
Rate Distance Using Distance Lookups
With the lookup approach, your business team manually creates records for each lane they want to cover, assigning a fixed mileage to each origin-destination pair. OTM uses Oracle’s built-in LOOKUP ONLY Rate Distance ID — no external system or configuration is needed beyond loading the data.
Step 1 — Create the Rate Distance record
YOUR_DOMAIN.LOOKUP_ONLY. Oracle provides a built-in record — use PUBLIC.LOOKUP ONLY if you do not need a custom one.LOOKUP. This tells OTM to use the pre-loaded distance table rather than calling an external engine.Save the record.
Step 2 — Create Distance Lookup records (Lane Definitions)
Each Distance Lookup record defines the mileage for one lane. Open the rate distance record you just created and navigate to the Distance Lookup section, or go to:
Common geo hierarchy options:
- CITY — city + state + country (e.g. Dallas, TX, USA)
- USZIP5 — 5-digit US zip code
- USZIP3 — 3-digit zip prefix (covers a broader area)
- LOCATION — a specific OTM Location record
- STATE/PROVINCE — state-level matching
920 with UOM MIAdd one record per lane. OTM matches an incoming shipment’s origin and destination against these records at plan time and reads the stored mileage.
Step 3 — Link to Rate Offering
In your Rate Offering (carrier contract) record, set the Rate Distance GID field to the Rate Distance ID you created above. OTM will then use the lookup table when costing shipments under that contract.
PUBLIC.LOOKUP ONLY rate distance, you can reference it directly in the Rate Offering without creating a custom Rate Distance record. Custom records are useful when you need different distance tables for different contracts.Rate Distance Using External Distance Engine (PCMiler)
PCMiler (from ALK Technologies) is a widely used routing engine that calculates distances based on road networks, route type, and address or postal code inputs. OTM integrates with PCMiler via a web service call at plan time.
This setup requires a PCMiler license and an API Authorization Key from ALK.
Step 1 — Create the External Distance Engine record
YOUR_DOMAIN.PCMILER_WS. Description can be something like DISTANCE BASED ON POSTAL CODES USING PCMILER/PRACTICAL - WSALKJava Classglog.business.rate.ratedistance.external.PCMilerEngineWSCache by XLane Don't Lookup - Don't Save. This prevents OTM from attempting to save results to a lookup table, which avoids errors when the distance cache tables are not in use.Parameters — the following rows are a sample configuration commonly used with PCMiler. OTM provides several additional parameters and the right combination depends on your business requirements and how your locations are set up.
| Parameter | Value | Country Code |
|---|---|---|
| BACKUP_WITH_LAT_LON | N | * |
| DEST_ADDRESS_TYPE | POSTAL_CODE | * |
| ROUTE_TYPE | P | * |
| SAME_SOURCE_DEST_DIST | 5 MI | * |
| SOURCE_ADDRESS_TYPE | POSTAL_CODE | * |
N — do not fall back to lat/lon coordinates if the postal code lookup failsPOSTAL_CODE — OTM passes the shipment's origin and destination postal codes to PCMiler for routingP — Practical route (fastest practical driving path). Other options include S (Shortest) and T (Toll-discouraged).5 MI — the distance OTM assigns when origin and destination postal codes are identical, avoiding a zero-distance resultGeo Hierarchy — add the following rows to tell OTM which address level to use when passing location data to PCMiler:
| Geo Hierarchy ID | Country Code |
|---|---|
| POSTAL_CODE | * |
| USZIP5 | USA |
Save the record.
Step 2 — Set up the PCMiler API Authorization Key
PCMiler requires an API key for authentication. In OTM, this is stored as a system property rather than directly on the External Distance Engine record.
Locate or create the property:
glog.ExternalDistanceEnginePCMilerWS.AuthorizationKeyOTM passes this key with every web service call to PCMiler. Keep this value secure — anyone with access to this property set can use the API license.
Step 3 — Create the Rate Distance record linking to the External Engine
YOUR_DOMAIN.PCMILEREXTERNALStep 4 — Link to Rate Offering
In your Rate Offering (carrier contract) record, set the Rate Distance GID field to the Rate Distance ID you created in Step 3. OTM will now call PCMiler at plan time to calculate the distance for each shipment costed under that contract.
BACKUP_WITH_LAT_LON = Y and ensuring your OTM Location records have latitude/longitude coordinates populated.