Carrier Recommendations

Carrier Recommendations Endpoint

Retrieve a list of recommended carriers operating near an origin, destination, or on a specified lane.

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.

Permissions

The external-api-carrier-recommendation permission is required to access this endpoint.

Endpoint

• URL: https://api.genlogs.io/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 origin city. Note that townships and counties are not accepted.

• origin_state (string, required): Full name or two-letter abbreviation of the origin state.

• destination_city (string, required): Name of the destination city. Note that townships and counties are not accepted.

• destination_state (string, required): Full name or two-letter abbreviation of the destination state.

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

Carried Cargo options:

• 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 (case sensitive string, optional): A list of equipment types and subtypes used by the carrier. You may list multiple values using a pipe (“|”) delimiter. You can specify a subtype by naming the parent class and child class separated by a colon. The scheme is Type 1: Subtype 1 | Type 2: Subtype 2 | Type 3: Subtype 3.

Equipment type options

Equipment Type	Subtype (Optional)
Dry Van	Moffett
Dry Van	Drop Frame
Dry Van	Double Pup
Reefer	Moffett
Flatbed	Step Deck
Flatbed	Moffett
Flatbed	Lowboy RGN
Flatbed	Logging
Flatbed	Gooseneck
Flatbed	Conestoga
Flatbed	Air Ride
Flatbed	53 Ft Flatbed
Box Truck
Car Hauler	Gooseneck
Dry Bulk	Hopper
Dry Bulk	Air Ride
Dry Bulk	Agricultural
Dump	Side Dump
Dump	Open Top
Dump	End Dump
Dump	Belly Dump
Intermodal	Gooseneck
Power Unit	Sleeper Cab
Power Unit	Day Cab
Tanker	Vacuum Tank
Tanker	Steel
Tanker	Cryogenic
Tanker	Compressed Gas
Tanker	Chemical
Tanker	Aluminum
Other	Wrecker
Other	Livestock Trailer
Other	High Tonnage Trailer

• 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

• power_only (boolean, optional): Filters carriers that operate tractors without owning trailers.

• broker_authority (boolean, optional): Filters carriers that have an active broker authority or not.

Search Tips

Perform and origin- or destination-only search

1. Origin-only search

   1. Fill out origin_city and origin_state

      1. Include destination_city and destination_state but leave the parameters null

      2. Omit the destination_radius parameter

2. Destination-only search

   1. Fill out destination_city and destination_state

   2. Include origin_city and origin_state but leave the parameters null

   3. Omit the origin_radius parameter

Note: If you receive a bad request, make sure to omit the origin_radius or destination_radius field.

Understanding contact information

Carrier Recommendations returns two sets of contact information: Onboarded Carrier fields and FMCSA fields.

• Onboarded Carrier fields: these values are provided by your Onboarded Carrier list, which admins can update in our UI. If no values are uploaded, they will be blank.

  • contact_email

  • contact_name

  • contact_phone

• FMCSA fields: these contact values are provided from the FMCSA. They are shown exactly as registered, including possible null values, multiple semicolon separated values, or values with typos.

  • telephone

  • email_address

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:

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

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

  • auth_months (number): Duration of the carrier’s authority in months.

  • authorized_for_hire (string): Indicates if the carrier is authorized for hire (Y/N).

  • bipd_insurance_on_file (number): Amount of Bodily Injury and Property Damage insurance on file (in US dollars).

  • broker_authority_status (string): Indicates if the carrier has broker authority status

    • A = Holds Active Authority

    • I = Inactive Authority

    • N = No Authority

  • 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_assessment (string): Assessment or notes about 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_ein (number): Employer Identification Number (EIN) of the carrier.

  • carrier_score (number): GenLogs proprietary carrier match score, incidating the likelihood of a carrier meeting the specific needs of a given search query. Carrier_score is composed of company_score, equipment_type_score, and lane_score.

  • carrier_score_scaled (number): The carrier_score on a scaled basis, with the best carrier for the lane scaling to 100%. Note that this is the score shown in our UI.

  • carrier_source (string): Source of the carrier data.

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

  • classdef (string): Classification of the carrier’s operation.

  • company_score (number): Score representing the carrier’s company performance or reliability.

  • contact_email (string): Email address of the carrier, provided by your Onboarded Carrier upload.

  • contact_name (string): Contact name of the carrier, provided by your Onboarded Carrier upload.

  • contact_phone (string): Phone number of the carrier, provided by your Onboarded Carrier upload.

  • contact_source (string): Source of the carrier’s contact information.

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

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

  • driver_total (number): Total number of drivers employed by the carrier.

  • email_address (string): FMCSA listed email address.

  • equipment_type_score (number): Score representing the suitability of the carrier’s equipment types.

  • equipment_types (string): Types of equipment operated by the carrier.

  • exempt_for_hire (string): Indicates if the carrier is exempt from for-hire regulations (Y/N).

  • federal_government (string): Indicates if the carrier is a federal government entity (Y/N).

  • indian_tribe (string): Indicates if the carrier is an Indian tribe entity (Y/N).

  • is_possible_backhaul (boolean): Indicates if the specified lane is a possible backhaul for the carrier based on their domicile address.

  • is_power_only (boolean): Carriers that operate tractors without owning trailers according to FMCSA records.

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

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

  • lane_score (number): Score representing the suitability of the carrier for a specific lane.

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

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

  • local_government (string): Indicates if the carrier is a local government entity (Y/N).

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

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

  • mcs150_date (string): Date of the carrier’s MCS-150 form submission.

  • mcs150_mileage (number): Annual mileage reported on the carrier’s MCS-150 form.

  • mcs150_mileage_year (number): Year of the mileage reported on the carrier’s MCS-150 form.

  • migrant (string): Indicates if the carrier transports migrant workers (Y/N).

  • name (string): Name of the carrier, often matching the legal name.

  • op_other (string): Indicates if the carrier has other operational classifications (Y/N).

  • operation_classification (string): Classification of the carrier’s operational authority according to the FMCSA (e.g. AUTHORIZED FOR HIRE).

  • phy_city (string): City of the carrier's domicile address.

  • phy_state (string): State of the carrier's domicile address.

  • phy_street (string): Street address of the carrier's domicile address.

  • phy_zip (string): City of the carrier's domicile address.

  • private_only (string): Carriers that are not for-hire, whose authority is solely for their own commercial enterprise, not available to the public at large (Y/N).

  • private_passenger_business (string): Indicates if the carrier transports private passengers for business (Y/N).

  • private_passenger_nonbusiness (string): Indicates if the carrier transports private passengers for non-business purposes (Y/N).

  • private_property (string): Indicates if the carrier transports private property (Y/N).

  • state_government (string): Indicates if the carrier is a state government entity (Y/N).

  • telephone (string): FMCSA listed telephone number.

  • us_mail (string): Indicates if the carrier transports U.S. mail (Y/N).

Request Example:

Get carrier recommendations based on location

get

Query parameters

origin_citystringRequired

Origin city for the recommendation

Default: NashvilleExample: Tennessee City

origin_statestringRequired

Origin state for the recommendation

Default: TNExample: Tennessee

destination_citystringRequired

Destination city for the recommendation

Default: DallasExample: Tascosa

destination_statestringRequired

Destination state for the recommendation

Default: TXExample: Texas

origin_radiusnumberOptional

Search radius around the origin location in miles

Default: 50Example: 50

destination_radiusnumberOptional

Search radius around the destination location in miles

Default: 50Example: 50

carrier_score_minnumberOptional

Minimum carrier score

Default: 0Example: 0

carrier_score_maxnumberOptional

Maximum carrier score

Default: 100Example: 100

fleet_size_minnumberOptional

Minimum fleet size

Default: 1Example: 1

fleet_size_maxnumberOptional

Maximum fleet size

Default: 500Example: 500

carried_cargostringOptional

Type of cargo carried

Default: general goodsExample: general goods

equipment_typesstringOptional

Type of equipment used by carriers

Default: flatbedExample: flatbed

preferred_carriersbooleanOptional

Filter for preferred carriers

Default: falseExample: true

real_timebooleanOptional

Request real-time data if available

Default: falseExample: true

auth_months_minnumberOptional

Minimum number of months a carrier has an active common or contract authority with FMCSA

Default: 1Example: 1

power_onlybooleanOptionalDefault: falseExample: true

broker_authoritybooleanOptionalDefault: falseExample: true

Header parameters

acceptstringRequired

Specifies the format of the response.

Default: application/jsonExample: application/json

Access-TokenstringRequired

Access Token for authentication

Example: [Token]

x-api-keystringRequired

API key for authentication

Example: [x-api-key]

Responses

200

The JSON response containing recommendations and lane volume

application/json

get

HTTPcURLJavaScriptPython

GET /carrier/recommendations HTTP/1.1
Host: api.genlogs.io
accept: application/json
Access-Token: [Token]
x-api-key: [x-api-key]
Accept: */*

200

The JSON response containing recommendations and lane volume

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