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

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

PreviousCreate token NextReal time Capabilities

Last updated 28 days ago