API Reference

Authentication

The Load To Truck API uses the API key to authenticate requests. You can view and manage your API keys in the Load To Truck console.

Your API key granting you access to API, so be sure to keep it secure! Do not share your secret API key in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via ApiKey HTTPS request header. Provide your API key as HTTPS Request headers: 'ApiKey': "Your-API-Key". You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors
  • HTTP 403 - Forbidden
  • error:{
      message: "API key is required",
      status: 403
    }
  • Description: HTTPS API request did not set "ApiKey" request header
  • HTTP 403 - Forbidden
  • error:{
      message: "API key is invalid",
      status: 403
    }
  • Description: Invalid API key passed to the API as HTTPS "ApiKey" request header

GET Load To Truck Ratio

GET request to /GetLoadToTruckRatio API endpoint returns the ratio that represents the balance between freight availability and truckload capacity in the spot market.

API can be queried by state, city, trailer and period parameters.

Request can pass parameters to API as a GET request query string, see Request parameters for more details

The response will be calculated for requested state, city, trailer and aggregated according to the requested period. See Response sections for more details.

Endpoint

  • https://api.loadtotruck.app/GetLoadToTruckRatio
  • Method GET
Request parameters
  • state - US state/Canada province, short code Required

    Example: send 'WA to get Load To Truck ratio for state 'Washington'

    Available states can be requested from GET Available States
  • city - City within selected state Optional

    Example: send 'SEATTLE' to get Load To Truck ratio for city 'SEATTLE'

    To verify that Load to Truck API can calculate the ratio for a selected city please call GET Available Cities
  • trailer - Trailer type Optional

    Example: send 'DRY VAN' to get Load To Truck ratio for trailer type 'DRY VAN'

    Available trailer types can be requested from GET Available Equipment
  • period - Period for which Load To Truck Ratio will be calculated. Required

    Supported periods: [LastMonth, UsStatesLastMonth, NextWeek, UsStatesNextWeek]

    LastMonth - Response will be aggregated Load to Truck Ratio for the preceding 30 days period for selected state, city, trailer.
    See LastMonth period response example.

    UsStatesLastMonth - Similar to the LastMonth, response will be aggregated Load to Truck Ratio for the preceding 30 days period for each US State and selected trailer, braked by state.
    state and city parameters are irrelevant for UsStatesLastMonth period.
    See UsStatesLastMonth period response example.

    NextWeek - The response will be aggregated Load to Truck Ratio for selected state, city, trailer for the next 5 days, braked by date. See NextWeek period response example.

    UsStatesNextWeek - Response will be aggregated Load to Truck Ratio for the next 5 days period for each US State and selected trailer, braked by state.
    state and city parameters are irrelevant for UsStatesNextWeek period.
    See UsStatesNextWeek period response example.

  • If request passes parameters to the API, the response will be calculated accordingly.

    Example: If GET request passes a trailer parameter to API, then API will return the Load to Truck ratio calculated for the requested trailer type.

  • Request example
                                                
    const request = require('request');
    
    function estimate_ratio() {
        return new Promise((resolve, reject) => {
            const url = 'https://api.loadtotruck.app/GetLoadToTruckRatio';
            const data = { 
            state: 'WA',
            city: 'SEATTLE',
            trailer: 'DRY VAN',
            period: 'nextweek'
           };
            request({
                headers: {
                    'ApiKey': '<your-api-key>'
                }, url: url,
                qs: data
            }, (err, response, body) => {
                if (err) {
                    return reject(err.error);
                }
                else {
                    if (response.statusCode != 200) {
                        return reject(JSON.parse(body).error);
                    }
                    resolve(JSON.parse(body).LoadToTruckRatio);
                }
            });
        });
    }
                                                
                                        
Load To Truck API Response has 4 different formats depending on the period request parameter.
LastMonth Response
  • HTTP status 200 - OK
  • API returns aggregated Load to Truck Ratio for the preceding 30 days period for selected state/city/trailer
    Response format: JSON
  •                                         
    {
        "LoadToTruckRatio": {
            fromDate: string, //From date 
            //example: "2019-01-01"
            toDate: string, //To date 
            //example: "2019-01-31"
            state: string, //US State/ Canada Province
            //example: "WA"
            ratio: number, //load to truck ratio
            //example: 0.5
            calculated: boolean, //true = successfully calculated, 
                                //false = not enough data to calculate ratio
            message: string,
            //example: "" / "Not enough data to calculate the ratio"
        }
    }                                       
                                        
Last Month US States Response
  • HTTP status 200 - OK
  • API returns aggregated Load to Truck Ratio for queried trailer for the preceding 30 days period, braked by US State
    Response format: JSON

    Response "statesresult" is an array [] of objects. Each object represents the Load to Truck Ratio for one US State.

  •                                         
     {
        "LoadToTruckRatio": {
            fromDate: string, //From date 
            //example: "2019-01-01"
            toDate: string, //To date 
            //example: "2019-01-31"
            "statesresult": [
                {
                    state: string, //US State
                    //example: "AL"
                    ratio: number, //load to truck ratio
                    //example: 0.5
                    calculated: boolean, //true = successfully calculated, 
                                         //false = not enough data to calculate ratio
                 message: string,
                    //example: "" / "Not enough data to calculate the ratio"
                },
                {
                    state: string, //US State
                    //example: "AK"
                    ...
                },
                {
                    state: string, //US State
                    //example: "AZ"
                    ...
                }
                ...
            ]
        }
    }
    
                                            
                                        
Next Week Response
  • HTTP status 200 - OK
  • API returns Load to Truck ratio for queried state/city/trailer
    Response format: JSON

    The response is an array [] of 5 objects. Each object represents the Load to Truck Ratio for one day.

    The first object in the array is a current date ratio. The last object is a ratio for the current date + 4 days.

  •                                         
     {
        "LoadToTruckRatio": [{
            date: string, //current date 
            //example: "2019-01-01" 
            ratio: number, //load to truck ratio
            //example: 0.5
            calculated: boolean, //true = successfully calculated, 
                                 //false = not enough data to calculate ratio
            message: string,
            //example: "" / "Not enough data to calculate the ratio"
        },
        {
            date: string, //current date + 1 day
            //example: "2019-01-02"
            ....
        },
        {
            date: string, //current date + 2 days
            //example: "2019-01-03"
            ....
        },
        {
            date: string, //current date + 3 days
            //example: "2019-01-04"
            ....
        },
        {
            date: string, //current date + 4 days
            //example: "2019-01-05"
            ....
        }]
     }
                                            
                                        
Next Week US States Response
  • HTTP status 200 - OK
  • API returns aggregated Load to Truck Ratio for queried trailer for the following 5 days period, braked by US State
    Response format: JSON

    Response "statesresult" is an array [] of objects. Each object represents the Load to Truck Ratio for one US State.

  •                                         
     {
        "LoadToTruckRatio": {
            fromDate: string, // Today 
            //example: "2019-11-28"
            toDate: string, //Today plus 5 days
            //example: "2019-12-03"
            "statesresult": [
                {
                    state: string, //US State
                    //example: "AL"
                    ratio: number, //load to truck ratio
                    //example: 0.5
                    calculated: boolean, //true = successfully calculated, 
                                         //false = not enough data to calculate ratio
                 message: string,
                    //example: "" / "Not enough data to calculate the ratio"
                },
                {
                    state: string, //US State
                    //example: "AK"
                    ...
                },
                {
                    state: string, //US State
                    //example: "AZ"
                    ...
                }
                ...
            ]
        }
    }
    
                                            
                                        

Errors

  • HTTP 500 Internal Server Error
  • error: {
     field: "state",
     message: "State/Province is required, please provide State/Province"
    }
  • Description: "state" is missing in HTTPS request query parameters
  • Available states can be requested from GET Available States

  • HTTP 500 Internal Server Error
  • error: {
     field: "state",
     message: "No loads found for state {state} "
    }
  • Description: HTTPS request "state" query parameter is invalid, no loads found for requested state
  • Available states can be requested from GET Available States

  • HTTP 500 Internal Server Error
  • error:{
      field: "city",
      message: "No loads found for {city} ({state}) city, please select one from available cities"
    }
  • Description: HTTPS request "city" query parameter is invalid, no loads found for requested city
  • To verify that Load to Truck API can calculate the ratio for a selected city please call GET Available Cities

  • HTTP 500 Internal Server Error
  • {
      field: "trailer",
      message: "No loads found for {trailer} trailer type"
    }
  • Description: HTTPS request "trailer" query parameter is invalid, no loads found for requested trailer
  • Available trailer types can be requested from GET Available Equipment

  • HTTP 500 Internal Server Error
  • {
      field: "period",
      message: "Period is required, please provide period

       {'LastMonth'/'UsStatesLastMonth'/'NextWeek'/'UsStatesNextWeek'}"
    }
  • Description: "period" is missing in HTTPS request query parameters
  • HTTP 500 Internal Server Error
  • {
      field: "period",
      message: "Period parameter is invalid, please choose one from available

       {'LastMonth'/'UsStatesLastMonth'/'NextWeek'/'UsStatesNextWeek'}"
    }
  • Description: HTTPS request "period" query parameter is invalid, valid values: ['LastMonth','UsStatesLastMonth','NextWeek','UsStatesNextWeek']

GET Available States

GET request to /GetAvailableStates API endpoint returns the array of US states and Canada provinces for which Load To Truck Ratio Api can calculate the ratio. This List depends on the volume of loads for each state/province that currently available on the market. If you cache the response, make sure to refresh it occasionally. Use state/province short code from the response list as state query parameter for /GetLoadToTruckRatio API endpoint.

Endpoint

  • https://api.loadtotruck.app/GetAvailableStates
  • Method GET
  • Request example
                                        
    const request = require('request');
        
    function get_available_states() {
        return new Promise((resolve, reject) => {
            const url = 'https://api.loadtotruck.app/GetAvailableStates';
            request({
                headers: {
                    'ApiKey': '<your-api-key>'
                }, url: url
            }, (err, response, body) => {
                if (err) {
                    return reject(err.error);
                }
                else {
                    if (response.statusCode != 200) {
                        return reject(JSON.parse(body).error);
                    }
                    resolve(JSON.parse(body).AvailableStates);
                }
            });
        });
    }
    
                                        
                                    
  • Response
    • HTTP status 200 - OK
    • Response format: JSON

      The response is an array [] of US states and Canada provinces for which Load To Truck Ratio Api can calculate the ratio.

    •                                 
      {
          "AvailableStates": [
              [
                  "OH", // state short code
                  "OHIO" // state name
              ],
              [
                  "IN", // state short code
                  "INDIANA" // state name
              ],
              [
                  "KY", // state short code
                  "KENTUCKY" // state name
              ],
              [
                  "FL", // state short code
                  "FLORIDA" // state name
              ],
              [
                  "SC", // state short code
                  "SOUTH CAROLINA" // state name
              ],
              [
                  "AL", // state short code
                  "ALABAMA" // state name
              ],
              [
                  "WI", // state short code
                  "WISCONSIN" // state name
              ],
              ... 
          ]
      }
          
                                      
                                  

    GET Available Cities

    Send GET request to /GetAvailableCities API endpoint to verify that Load To Truck Ratio Api can calculate the ratio for a selected city.

    Endpoint

    • https://api.loadtotruck.app/GetAvailableCities
    • Method GET
    Request parameters
    • state - US state/Canada province short code Required

      Example: send 'WA to for state Washington

      Available states can be requested from GET Available States
    • city - City within selected state Required

      Example: 'SEATTLE'

    • Request example
                                                  
      const request = require('request');
      
      function get_available_cities() {
          return new Promise((resolve, reject) => {
              const url = 'https://api.loadtotruck.app/GetAvailableCities';
              const data = { state: 'WA',
              city: 'SEATTLE'
             };
              request({
                  headers: {
                      'ApiKey': '<your-api-key>'
                  }, url: url,
                  qs: data
              }, (err, response, body) => {
                  if (err) {
                      return reject(err.error);
                  }
                  else {
                      if (response.statusCode != 200) {
                          return reject(JSON.parse(body).error);
                      }
                      resolve(JSON.parse(body).AvailableCities);
                  }
              });
          });
      }
                                                  
                                          
    Response
    • HTTP status 200 - OK
    • Response format: JSON

      The response is an array [] of objects of states and cities
      {
        state: {state},
        city: {city}
      }
      for which Load To Truck Ratio Api can calculate the ratio.

    • Get Available Cities API Response has 3 different formats.
    • Response example
      Exactly one city found
      Use city from the response list as city query parameter for /GetLoadToTruckRatio API endpoint.
                                      
      {
          "AvailableCities": [
              {
                  "city": "SEATTLE",
                  "state": "WA"
              }
          ]
      }
                                               
                                          
    • Response example
      No city found
      Empty response from /GetAvailableCities API means that selected city can not be used as a city parameter to /GetLoadToTruckRatio API endpoint.
                                          
      {
          "AvailableCities": []
      }        
                                                  
                                              
    • Response example
      Multiple city suggestions found
      No exact city is found for requested state/ city parameters. But /GetAvailableCities API is capable to provide suggestions. The response is a list of proposed cities for which /GetLoadToTruckRatio can calculate the ratio.
                                              
      {
          "AvailableCities": [
              {
                  "city": "SUMNER",
                  "state": "WA"
              },
              {
                  "city": "SHELTON",
                  "state": "WA"
              },
              {
                  "city": "SEATTLE",
                  "state": "WA"
              },
              {
                  "city": "SELAH",
                  "state": "WA"
              },
              {
                  "city": "SUMAS",
                  "state": "WA"
              },
              {
                  "city": "SPOKANE",
                  "state": "WA"
              },
              ...
          ]
      }       
                                                      
                                                  

    Errors

    • HTTP 500 Internal Server Error
    • error: {
       field: "state",
       message: "Please provide State/Province"
      }
    • Description: "state" is missing in HTTPS request query parameters
    • Available states can be requested from GET Available States

    • HTTP 500 Internal Server Error
    • error: {
       field: "city",
       message: "City is required, please provide city for selected state"
      }
    • Description: "city" is missing in HTTPS request query parameters

    GET Available Equipment

    GET request to /GetAvailableEquipment API endpoint returns the list of trailer/transportation equipment types for which Load To Truck Ratio Api can calculate the ratio. This List depends on the volume of loads for each trailer/transportation equipment type that currently available on the market. If you cache the response, make sure to refresh it occasionally. Use entry from response AvailableEquipment[] list as trailer query parameter for /GetLoadToTruckRatio API endpoint.

    Endpoint

    • https://api.loadtotruck.app/GetAvailableEquipment
    • Method GET
  • Request example
                                                        
    const request = require('request');
            
    function get_available_equipment() {
        return new Promise((resolve, reject) => {
            const url = 'https://api.loadtotruck.app/GetAvailableEquipment';
            request({
                headers: {
                    'ApiKey': '<your-api-key>'
                }, url: url
            }, (err, response, body) => {
                if (err) {
                    return reject(err.error);
                }
                else {
                    if (response.statusCode != 200) {
                        return reject(JSON.parse(body).error);
                    }
                    resolve(JSON.parse(body).AvailableEquipment);
                }
            });
        });
     }
                                                        
                                                
  • Response
    • HTTP status 200 - OK
    • Response format: JSON

      The response is an array [] of trailer/transportation equipment types for which Load To Truck Ratio Api can calculate the ratio.

    •                                     
      {
          "AvailableEquipment": [
              "FLATBED",
              "VAN",
              "REEFER",
              "STEPDECK",
              "POWER ONLY",
              "DRY VAN",
              "CONTAINER",
              "STEP DECK",
              "TARPS",
              "FLATBED W",
              "FLATBED MAXI",
              "VAN HAZMAT",
              "DUMP TRAILER",
              "HOTSHOT",
              "AUTO CARRIER",
              "HOPPER BOTTOM",
              "SIDES",
              "LOWBOY",
              "REM GOOSENECK",
              "VAN VENTED",
              "FLATBED HAZMAT",
      
              ...
      
          ]
      }                                    
                                      
    Questions
    • If you have a question or need help implementing integration with Load To Truck API, please send us a message: admin@loadtotruck.app