# 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.](#user-content-fn-1)[^1] * [**origin_state** (string, optional): Full name or two-letter abbreviation of the origin state.](#user-content-fn-1)[^1] * [**destination_city** (string, optional): Name of the destination city. Note that townships and counties are not accepted.](#user-content-fn-1)[^1] * [**destination_state** (string, optional): Full name or two-letter abbreviation of the destination state.](#user-content-fn-1)[^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 ```json {"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":{"":{