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

  Possible values:

  • Reefer

  • Flatbed

  • Tanker

  • Dry Bulk

  • Dump

  • Container

  • Car Hauler

  • Dry Van

  Examples:

  • equipment_types: Dry Van | Box Truck

  • equipment_types: Dry Van: Double Pup | Box Truck | Flatbed: Step deck | Flatbed: Lowboy RGN

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

Search Tips

To perform and origin- or destination-only search, follow these steps.

Origin-only search

• Fill out origin_city and origin_state

• Include destination_city and destination_state but leave the parameters null

• Omit the destination_radius parameter

Destination-only search

• Fill out destination_city and destination_state

• Include origin_city and origin_state but leave the parameters null

• Omit the origin_radius parameter

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

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.

  • 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 (number): The carrier match score is a metric that indicates the likelihood of a carrier meeting the specific needs of a given search query.

  • 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_possible_backhaul (boolean): indicates if the specified lane is a possible backhaul for the carrier

  • 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

  • is_power_only (boolean): Carriers that operate tractors without owning trailers.

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