---
title: "SONAR Lane Scores"
method: POST
path: "/truckload/capacity/sonar_lane_scores"
tags: ["Truckload"]
---

# SONAR Lane Scores

`POST /truckload/capacity/sonar_lane_scores`

This endpoint allows permissioned users to call and return our SONAR Lane Scores at a KMA (Key Market Area) to KMA lane level. The scores provided in this endpoint measure the balance of the flow of capacity in a lane. Outbound heavy lanes are scored lower while lanes that originate in areas with heavy inbound score higher. SONAR Lane Scores are updated daily, the scores provided in this endpoint are an average based on the start and end date in the request. If you'd like to get a lane score for a single point in time you can make the start and end dates the same.

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

Returns lane scores based off of SONAR internal metrics. This endpoint handles the following input fields:

*   start\_date: the start date of the range over which the Lane Scores are being requested (YYYY-MM-DD); required field
*   end\_date: the end date of the range over which the Lane Scores are being requested (YYYY-MM-DD); required field
*   lanes: an embedded list of the following fields:

*   lane\_id: a unique identifier set by the client and will be returned with the response; optional
*   origin: the 3 character airport code for the origin Key Market Area (KMA), required
*   destination: the 3 character airport code for the destination Key Market Area (KMA), required
*   equipment\_type: must be ‘VAN’ or ‘REEFER’; required
*   origin\_country\_code: country code for the origin; at this time only the 135 contiguous US markets are available, must be ‘USA’, required
*   destination\_country\_code: country code for the destination; at this time only the 135 contiguous US markets are available, must be ‘USA’, required

Here are the output fields returned in a successful call:

*   lane\_scores: A list objects that contain the output information associated with the valid requested lanes
    *   lane\_id: the unique identifier sent in the corresponding call
    *   data\_timestamp: the date for which the data in the response was calculated
    *   origin:the 3 character airport code for the origin Key Market Area (KMA) provided in the API call by the client
    *   origin\_country\_code: ‘USA’, will return an error if anything other than ‘USA’ is entered
    *   destination: the 3 character airport code for the destination Key Market Area (KMA) provided in the API call by the client
    *   destination\_country\_code: ‘USA’, will return an error if anything other than ‘USA’ is entered
    *   equipment\_type: the equipment\_type provided in the API call by the client
    *   lane\_score: the Lane Score for the provided lane
    *   capacity\_indicator: a small bit of text explaning the Lane Score
*   errors: a list of objects that contains information on lanes that are not valid for the request
    *   lane\_id: the unique identifier sent in the corresponding call
    *   origin:the 3 character airport code for the origin Key Market Area (KMA) provided in the API call by the client
    *   origin\_country\_code: ‘USA’
    *   destination: the 3 character airport code for the destination Key Market Area (KMA) provided in the API call by the client
    *   destination\_country\_code: ‘USA’
    *   equipment\_type: the equipment\_type provided in the API call by the client
    *   error: a specific explanation of the issue with the lane information that caused the error

## Headers

- `x-api-version` string

## Request body

- LaneScoreAverageRequest
  - `start_date` string, date-time, required
  - `end_date` string, date-time, required
  - `lanes` LaneScoreLane[], required
    - `lane_id` string
    - `origin` string, required
    - `destination` string, required
    - `equipment_type` 'UNKNOWN' | 'VAN' | 'REEFER' | 'FLATBED', required
    - `origin_country_code` 'UNKNOWN' | 'USA' | 'CAN' | 'MEX', required
    - `destination_country_code` 'UNKNOWN' | 'USA' | 'CAN' | 'MEX', required

## Response `200`

OK

- LaneScoreAverageResponse[]
  - `lane_scores` LaneScoreAverageResult[], required
    - `lane_id` string
    - `start_date` string, date-time
    - `end_date` string, date-time
    - `origin` string
    - `origin_country_code` string
    - `destination` string
    - `destination_country_code` string
    - `equipment_type` string
    - `lane_score` integer
    - `capacity_indicator` string
  - `errors` LaneScoreError[], required
    - `lane` LaneScoreLane
      - `lane_id` string
      - `origin` string, required
      - `destination` string, required
      - `equipment_type` 'UNKNOWN' | 'VAN' | 'REEFER' | 'FLATBED', required
      - `origin_country_code` 'UNKNOWN' | 'USA' | 'CAN' | 'MEX', required
      - `destination_country_code` 'UNKNOWN' | 'USA' | 'CAN' | 'MEX', required
    - `error` 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)