--- title: "TRAC Forecast Statistics" method: POST path: "/v2/truckload/rates/trac/forecast/statistics" tags: ["Truckload V2"] --- # TRAC Forecast Statistics `POST /v2/truckload/rates/trac/forecast/statistics` This endpoint allows permissioned users to get statistical aggregations (min, median, average, max, standard deviation) of TRAC forecast rates over specified time periods. The statistics can be aggregated by various time periods including summary (all forecasts in range), weekly, monthly, quarterly, yearly, or week-to-date. The endpoint supports retrieving statistics for both historical and future forecasts. 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 statistics alongside current data. OD pairs can be defined with market airport codes, Zip3 or Zip5, supporting any combination. If input miles are not specified in the request, they will be calculated and all forecasts returned will be adjusted to the lane's specific mileage. 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 range over which statistics are being requested (YYYY-MM-DD), must be on or after 2024-01-01, required * end\_date: the most recent date of the range over which statistics are being requested (YYYY-MM-DD), must be within 365 days of start\_date and cannot exceed one year from today, required * aggregation: time period for aggregation - 'SUMMARY', 'WEEKLY', 'MONTHLY', 'QUARTERLY', 'YEARLY', or 'WTD' (week-to-date), required * 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 * input\_miles: the specific lane miles the forecasts will be adjusted to; this field is optional but must not be negative and will be calculated if not provided, not required Here are the output fields returned in a successful call: * lanes: A list object that contains the output information associated with the valid requested lanes * lane\_id: the unique identifier sent in the corresponding call * miles: the mileage for the lane * mileage\_type: the type of mileage used, either input or calculated * origin: the Zip3/Zip5 or 3 character airport code for the lane origin, as provided in the request * origin\_market: the 3 character airport code for the origin Key Market Area (KMA) * 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\_market: the 3 character airport code for the destination Key Market Area (KMA) * 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 statistics in the response apply) * data\_timestamp: the date for which the data in the response was calculated * period\_start\_date: the start date for this statistical period * period\_end\_date: the end date for this statistical period * aggregation: the aggregation type used for this period (SUMMARY, WEEKLY, MONTHLY, QUARTERLY, YEARLY, or WTD) * lowest\_forecast\_rpm: the lowest (minimum) forecast rate-per-mile value in the period * highest\_forecast\_rpm: the highest (maximum) forecast rate-per-mile value in the period * median\_forecast\_rpm: the median forecast rate-per-mile value in the period * avg\_forecast\_rpm: the average forecast rate-per-mile value in the period * std\_dev\_forecast\_rpm: the standard deviation of forecast rate-per-mile values in the period * lowest\_forecast\_index: the lowest (minimum) forecast adjustment index value in the period * highest\_forecast\_index: the highest (maximum) forecast adjustment index value in the period * median\_forecast\_index: the median forecast adjustment index value in the period * avg\_forecast\_index: the average forecast adjustment index value in the period * std\_dev\_forecast\_index: the standard deviation of forecast adjustment index values in the period * lowest\_forecast\_customer\_rate: the lowest (minimum) forecast customer rate value in the period (only populated if current\_customer\_rate was provided) * highest\_forecast\_customer\_rate: the highest (maximum) forecast customer rate value in the period (only populated if current\_customer\_rate was provided) * median\_forecast\_customer\_rate: the median forecast customer rate value in the period (only populated if current\_customer\_rate was provided) * avg\_forecast\_customer\_rate: the average forecast customer rate value in the period (only populated if current\_customer\_rate was provided) * std\_dev\_forecast\_customer\_rate: the standard deviation of forecast customer rate values in the period (only populated if current\_customer\_rate was provided) * errors: a list object that contains information on lanes that are not valid for the forecast statistics request * lane\_id: the unique identifier sent in the corresponding call * origin: the origin string provided in the request * origin\_country\_code: 'USA' * destination: the destination string provided in the request * destination\_country\_code: 'USA' * equipment\_type: the equipment\_type provided in the API call by the client * input\_miles: the miles provided by the user in the request or calculated (if origin and destination inputs were valid) * error\_found: A lane/date/equipment specific explanation of the issue with the lane information that caused an error ## Headers - `x-api-version` string ## Request body - TracForecastStatisticsJsonRequest - `start_date` string, date-time, required - `end_date` string, date-time, required - `aggregation` string, required - `lanes` TracForecastStatisticsLaneJsonRequest[], required - `lane_id` string - `origin` string, required - `origin_country_code` string, required - `destination` string, required - `destination_country_code` string, required - `equipment_type` string, required - `input_miles` number, double - `current_customer_rate` number, double ## Response `200` OK - TracForecastStatisticsJsonResponse - `lanes` TracForecastLaneStatistics[], required - `lane_id` string, required - `miles` number, double, required - `mileage_type` string, required - `origin` string, required - `origin_market` string, required - `origin_country_code` string, required - `destination` string, required - `destination_market` string, required - `destination_country_code` string, required - `equipment_type` string, required - `data_timestamp` string, date-time, required - `period_start_date` string, date-time, required - `period_end_date` string, date-time, required - `aggregation` string, required - `lowest_forecast_rpm` number, double, required - `highest_forecast_rpm` number, double, required - `median_forecast_rpm` number, double, required - `avg_forecast_rpm` number, double, required - `std_dev_forecast_rpm` number, double, required - `lowest_forecast_index` number, double, required - `highest_forecast_index` number, double, required - `median_forecast_index` number, double, required - `avg_forecast_index` number, double, required - `std_dev_forecast_index` number, double, required - `lowest_forecast_customer_rate` number, double - `highest_forecast_customer_rate` number, double - `median_forecast_customer_rate` number, double - `avg_forecast_customer_rate` number, double - `std_dev_forecast_customer_rate` number, double - `errors` TracStatisticsJsonError[], required - `lane_id` string - `origin` string - `origin_country_code` string - `destination` string - `destination_country_code` string - `equipment_type` string - `input_miles` number, double - `error_found` string --- [API](https://skmtc.net/freightwaves/apis/sonar-api.md) · [All operations](https://skmtc.net/freightwaves/apis/sonar-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/freightwaves/sonar-api/revisions/3a995f316cda/schema)