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

  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
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"
    }
  ]
}

Last updated