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, optional): Name of the origin city. Note that townships and counties are not accepted.[^1]

• origin_state (string, optional): Full name or two-letter abbreviation of the origin state.[^1]

• destination_city (string, optional): Name of the destination city. Note that townships and counties are not accepted.[^1]

• destination_state (string, optional): Full name or two-letter abbreviation of the destination state.[^1]

• origin_radius (int, optional): Radius (miles) around the origin location for carrier search - default 50 miles (max. 100 miles).

• destination_radius (int, optional): Radius (miles) around the destination location for carrier search - default 50 miles (max. 100 miles).

• carrier_score_min (float, optional): Minimum acceptable carrier score - default to 0.

  • Accepts values between 0 and 1

• carrier_score_max (float, optional): Maximum acceptable carrier score - default to 1

  • Accepts values between 0 and 1. Generally, we recommend omitting this parameter

• 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

• preferred_carriers: (boolean, optional): Only return carriers that match your Onboarded Carrier list, as configured in the web application.

• 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 also have a brokerage arm.

• is_possible_backhaul (boolean, optional): Filters to only return carriers where the specified lane is a possible backhaul based on their domicile address proximity to the destination.

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

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, indicating the likelihood of a carrier meeting the specific needs of a given search query.
  • 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_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.
  • confirmed_email (object): List of available emails.
  • confirmed_phone (object): List of available phone numbers.
  • 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.
  • 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

Get carrier recommendations based on location

{"openapi":"3.0.2","info":{"title":"Carrier API","version":"1.0.1"},"servers":[{"url":"https://api.genlogs.io"}],"paths":{"/carrier/recommendations":{"get":{"parameters":[{"name":"accept","in":"header","required":true,"schema":{"type":"string","default":"application/json"},"description":"Specifies the format of the response."},{"name":"Access-Token","in":"header","required":true,"schema":{"type":"string"},"description":"Access Token for authentication"},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"API key for authentication"},{"in":"query","name":"origin_city","required":true,"schema":{"type":"string","default":"Nashville"},"description":"Origin city for the recommendation"},{"in":"query","name":"origin_state","required":true,"schema":{"type":"string","default":"TN"},"description":"Origin state for the recommendation"},{"in":"query","name":"destination_city","required":true,"schema":{"type":"string","default":"Dallas"},"description":"Destination city for the recommendation"},{"in":"query","name":"destination_state","required":true,"schema":{"type":"string","default":"TX"},"description":"Destination state for the recommendation"},{"default":50,"in":"query","name":"origin_radius","schema":{"type":"number","default":50},"description":"Search radius around the origin location in miles"},{"default":50,"in":"query","name":"destination_radius","schema":{"type":"number","default":50},"description":"Search radius around the destination location in miles"},{"default":0,"in":"query","name":"carrier_score_min","schema":{"type":"float","default":0},"description":"Minimum carrier score"},{"default":100,"in":"query","name":"carrier_score_max","schema":{"type":"float","default":1},"description":"Maximum carrier score"},{"default":"None","in":"query","name":"fleet_size_min","schema":{"type":"number"},"description":"Minimum fleet size"},{"default":"None","in":"query","name":"fleet_size_max","schema":{"type":"number"},"description":"Maximum fleet size"},{"in":"query","name":"carried_cargo","schema":{"type":"string","default":"general goods"},"description":"Type of cargo carried"},{"in":"query","name":"equipment_types","schema":{"type":"string","default":"flatbed"},"description":"Type of equipment used by carriers"},{"in":"query","name":"preferred_carriers","schema":{"type":"boolean","default":false},"description":"Filter for preferred carriers"},{"in":"query","name":"real_time","schema":{"type":"boolean","default":false},"description":"Request real-time data if available"},{"in":"query","name":"auth_months_min","schema":{"type":"number","default":1},"description":"Minimum number of months a carrier has an active common or contract authority with FMCSA"},{"in":"query","name":"power_only","schema":{"type":"boolean","default":false}},{"in":"query","name":"broker_authority","schema":{"type":"boolean","default":false}},{"in":"query","name":"is_possible_backhaul","schema":{"type":"boolean","default":false}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarrierResponse"}}},"description":"The JSON response containing recommendations and lane volume"}},"summary":"Get carrier recommendations based on location"}}},"components":{"schemas":{"CarrierResponse":{"properties":{"real_time_locs":{"items":{"$ref":"#/components/schemas/CarrierRealTimeLocs"},"type":"array"},"recommendations":{"items":{"$ref":"#/components/schemas/CarrierRecommendation"},"type":"array"}},"required":["real_time_locs","recommendations"],"type":"object"},"CarrierRealTimeLocs":{"properties":{"current_lat":{"nullable":true,"type":"number"},"current_lon":{"nullable":true,"type":"number"},"dot_number":{"type":"string"},"is_inbound":{"type":"boolean"}},"required":["dot_number","is_inbound"],"type":"object"},"CarrierRecommendation":{"properties":{"add_date":{"type":"string"},"bipd_insurance_on_file":{"type":"number"},"cargo_insurance_on_file":{"type":"number"},"carried_cargo":{"type":"string"},"carrier_driver_oos_rate":{"type":"number"},"carrier_driver_oos_rate_national_avg":{"type":"number"},"carrier_score_scaled":{"type":"number"},"carrier_total_power_units":{"type":"number"},"carrier_vehicle_oos_rate":{"type":"number"},"carrier_vehicle_oos_rate_national_avg":{"type":"number"},"confirmed_email":{"type":"object","properties":{"<email@domain.com>":{