TRAC Forecast Rates

This endpoint allows permissioned users to retrieve SONAR KMA TRAC forecast rates for specified lanes over a defined date range. The forecast data is derived from historical TRAC spot rate patterns and provides estimates of future pricing trends based on market conditions, seasonal factors, and load behavior.

Forecast data supports retrieving both historical and future forecasts spanning up to 365 days. The date range can extend from 2024-01-01 through one year beyond the current date, with a maximum span of 365 days between start_date and end_date. This enables backtesting scenarios using historical forecast data alongside current data. Each lane request must include valid origin/destination pairs defined by KMA airport codes, Zip3, or Zip5. The system will validate that all input lanes are within supported markets (contiguous US only).

A comprehensive list of KMAs, their airport codes, and the zip3's associated with those KMA's can be found by calling the KMA Reference List endpoint located under the "Lookup" menu. Additionally, the Zip3 Specific endpoint (also located under the Lookup tab), will return the airport code associated with a zip3 under the "qualifier" header (along with the reference city and state).

You can click on the Body Sample to the right to populate the example in the test body below.

For more information about getting access to this endpoint or using this endpoint, please reach out to our Customer Success team (cs@gosonar.com).

This endpoint handles the following input fields:

• start_date: the earliest date of the forecast range (YYYY-MM-DD), must be on or after 2024-01-01, required
• end_date: the latest date of the forecast range (YYYY-MM-DD), must be within 365 days of start_date and cannot exceed one year from today, required
• lanes: an array of lane objects, each containing:
  • lane_id: a unique identifier set by the client and will be returned with the response; optional field, not required
  • origin: the 3 character KMA airport code, Zip3 or Zip5 for the origin, required
  • origin_country_code: country code for the origin; at this time only lanes within the contiguous US markets are available, must be ‘USA’, required
  • destination: the 3 character KMA airport code, Zip3 or Zip5 for the destination, required
  • destination_country_code: country code for the destination; at this time only lanes within the contiguous US markets are available, must be ‘USA’, required
  • equipment_type: may be ‘VAN’ or ‘REEFER’ or ‘FLATBED’, required
  • current_customer_rate: current rate (rpm or all-in) the customer is using on the lane. Optional.
  • input_miles: customer's specific mileage for the lane, optional. Will use SONAR internal mileage system if not set.

Here are the output fields returned in a successful call:

• Lanes: A list object that contains the forecast information associated with the valid requested lanes
  • lane_id: the unique identifier sent in the corresponding call
  • origin: the Zip3/Zip5 or 3 character airport code for the lane origin, as provided in the request
  • origin_country_code: the 3 character country code the for origin, 'USA'
  • destination: the Zip3/Zip5 or 3 character airport code for the lane destination, as provided in the request
  • destination_country_code: the 3 character country code the for destination, 'USA'
  • equipment_type: the equipment_type provided in the API call by the client (for which the forecast applies)
  • lane_id: the unique lane id provided in the request
  • mileage_type: "INTERNAL" or "INPUT", depending on if `input_miles` was provided in the request
  • miles: mileage for the lane (provided or calculated)
  • current_customer_rate: the customer's rate provided in the request
  • forecast_index_value: position
  • forecast_rpm_trac: trac forecast rpm
  • forecast_rate_customer: the seasonal forecast for the customer's lane, if they provided a starting rate.
• Errors: a list object that contains information on lanes that are not valid for the forecast request
  • original_lane: the lane from the request body
  • error_found: A lane/date/equipment specific explanation of the issue with the lane information that caused an error