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.
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.
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
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
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:
Origin city for the recommendation
Nashville
Example: Tennessee City
Origin state for the recommendation
TN
Example: Tennessee
Destination city for the recommendation
Dallas
Example: Tascosa
Destination state for the recommendation
TX
Example: Texas
Search radius around the origin location in miles
50
Example: 50
Search radius around the destination location in miles
50
Example: 50
Minimum carrier score
0
Example: 0
Maximum carrier score
100
Example: 100
Minimum fleet size
1
Example: 1
Maximum fleet size
500
Example: 500
Type of cargo carried
general goods
Example: general goods
Type of equipment used by carriers
flatbed
Example: flatbed
Filter for preferred carriers
false
Example: true
Request real-time data if available
false
Example: true
Minimum number of months a carrier has an active common or contract authority with FMCSA
1
Example: 1
false
Example: true
false
Example: true
Specifies the format of the response.
application/json
Example: application/json
Access Token for authentication
[Token]
API key for authentication
[x-api-key]
GET /carrier/recommendations HTTP/1.1
Host: api.genlogs.io
accept: application/json
Access-Token: [Token]
x-api-key: [x-api-key]
Accept: */*
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