Carrier Recommendations

Carrier Recommendations Endpoint

The carrier recommendations endpoint allows a user to retrieve a list of recommended carriers operating on a specified lane (origin and destination locations).

Authentication

• Include your Access-Token in the header of your requests.

• Include your x-api-key The API key provided by GenLogs. This header must be included in the request.

Endpoint

• URL: https://api.genlogs.com/carrier/recommendations

• Method: GET

Headers

• Access-Token: token (string, required): The access token obtained from the "Create Access Token" endpoint.

• x-api-key (string, required): The API key provided by GenLogs. This header must be included in the request

Query Parameters:

• origin_city (string, required): Name of the city of the starting location.

• origin_state (string, required): Name of the state of the starting location.

• destination_city (string, required): Name of the city of the destination location.

• destination_state (string, required): Name of the state of the destination location.

• origin_radius (number, optional): Radius (miles) around the origin location for carrier search - default 50 miles

• destination_radius (number, optional): Radius (miles) around the destination location for carrier search - default 50 miles.

• carrier_score_min (number, optional): Minimum acceptable carrier score.

• carrier_score_max (number, optional): Maximum acceptable carrier score.

• fleet_size_min (number, optional): Minimum fleet size of carriers - default 0 power units

• fleet_size_max (number, optional): Maximum fleet size of carriers - default 1000 power units

• carried_cargo (string, optional): Type of cargo registered to carried., Possible values:

  • Passengers

  • Garbage/Refuse

  • Mobile Homes

  • Drive/Tow away

  • Water Well

  • Livestock

  • Utilities

  • Agricultural/Farm Supplies

  • General Freight

  • Household Goods

  • US Mail

  • Beverages

  • Paper Products

  • Fresh Produce

  • Meat

  • Refrigerated Food

  • Metal: sheets, coils rolls

  • Logs, Poles, Beams, Lumber

  • Building Materials

  • Machinery, Large Objects

  • Oilfield Equipment

  • Construction

  • Liquids/Gases

  • Chemicals

  • Motor Vehicles

  • Grain Feed Hay

  • Coal/Coke

  • Commodities Dry Bulk

  • Intermodal Cont.

• equipment_types (string, optional): Type of equipment registered to carried. Possible values: :

  • Reefer

  • Flatbed

  • Tanker

  • Dry Bulk

  • Dump

  • Container

  • Car Hauler

  • Dry Van

• preferred_carriers: (boolean, optional): Only return carriers marked as preferred.

• auth_months_min (number, optional, default=1): Minimum number of months a carrier has an active common or contract authority with FMCSA

Response:

• 200 OK: A JSON object containing recommendations and lane volume details.

• 400 Bad Request: If required parameters are missing or invalid.

• 401 Unauthorized: If the authentication credentials (email and password) are missing or incorrect.

• 403 Forbidden: Access to the requested resource is forbidden.

• 500 Internal Server Error: If there is an issue on the server that prevents processing the request.

Response Body:

• lane_volume (array of LaneVolume objects): Information about the lane volume.

  • lane_volume (number): The volume of the lane.

  • start_of_week (string): The start date of the week for the lane volume data.

• recommendations (array of CarrierRecommendation objects): List of recommended carriers.

  • add_date (string): Date the recommendation was added.

  • bipd_insurance_on_file (number): Amount in of BIPD insurance on file (in US dollars)

  • cargo_insurance_on_file (number): Amount of cargo insurance on file (in US dollars)

  • carried_cargo (string): Type of cargo carried by the carrier.

  • carrier_driver_oos_rate (number): Carrier’s driver Out-of-Service (OOS) rate.

  • carrier_driver_oos_rate_national_avg (number): National average OOS rate for drivers.

  • carrier_score_scaled (number): The carrier's score on a scaled basis.

  • carrier_total_power_units (number): Total power units operated by the carrier.

  • carrier_vehicle_oos_rate (number): Carrier’s vehicle OOS rate.

  • carrier_vehicle_oos_rate_national_avg (number): National average OOS rate for vehicles.

  • dba_name (nullable string): Doing Business As (DBA) name of the carrier.

  • dot_number (string): DOT number of the carrier.

  • email_address (string): Email address of the carrier, provided by the FMCSA.

  • is_visually_sighted (boolean): Whether the carrier has been visually sighted.

  • is_preferred (boolean): Whether the carrier has been marked as preferred or not.

  • lat (nullable number): Latitude of the FMCSA registered address.

  • legal_name (string): Legal name of the carrier.

  • lon (nullable number): Longitude of the FMCSA registered address.

  • mc_number (number): Motor Carrier (MC) number of the carrier.

  • phy_city (string): Physical city location of the carrier.

  • phy_state (string): Physical state location of the carrier.

  • phy_street (string): Physical street address of the carrier.

  • phy_zip (string): Physical ZIP code of the carrier.

  • telephone (string): FMCSA listed telephone number

Request Example:

Get carrier recommendations based on location and drive time

GEThttps://api.genlogs.io/carrier/recommendations

Query parameters

Header parameters

Response

200

The JSON response containing recommendations and lane volume

Body

application/json

real_time_locs*array of CarrierRealTimeLocs (object)

recommendations*array of CarrierRecommendation (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.genlogs.io/carrier/recommendations?origin_city=Tennessee+City&origin_state=Tennessee&destination_city=Tascosa&destination_state=Texas&drive_time=2', {
    method: 'GET',
    headers: {
      "accept": "application/json",
      "Access-Token": "[Token]",
      "x-api-key": "[x-api-key]"
    },
});
const data = await response.json();

Response

200

{
  "real_time_locs": [
    {
      "current_lat": 0,
      "current_lon": 0,
      "dot_number": "text",
      "is_inbound": false
    }
  ],
  "recommendations": [
    {
      "add_date": "text",
      "bipd_insurance_on_file": 0,
      "cargo_insurance_on_file": 0,
      "carried_cargo": "text",
      "carrier_driver_oos_rate": 0,
      "carrier_driver_oos_rate_national_avg": 0,
      "carrier_score_scaled": 0,
      "carrier_total_power_units": 0,
      "carrier_vehicle_oos_rate": 0,
      "carrier_vehicle_oos_rate_national_avg": 0,
      "dba_name": "text",
      "dot_number": "text",
      "email_address": "text",
      "is_inbound": false,
      "is_real_time": false,
      "is_visually_sighted": false,
      "lat": 0,
      "legal_name": "text",
      "lon": 0,
      "mc_number": 0,
      "phy_city": "text",
      "phy_state": "text",
      "phy_street": "text",
      "phy_zip": "text",
      "telephone": "text"
    }
  ]
}