# Carrier Observation

{% hint style="info" %}
_Exclusive access. This endpoint is only available to insurance customers. Contact your Customer Success Manager or GenLogs point of contact to request access._
{% endhint %}

The Carrier Observation API provides carrier information based on sightings in the GenLogs Sensor network, FMCSA Inspection Data, and other observation data as available.

This information can help assess risk profiles, verify carrier operations, determine territory pricing, make informed underwriting decisions, and more.

### **Authentication**

Include the following headers in your requests:

* **Access-Token:** The access token obtained from the "Create Acess Token" endpoint.
* **x-api-key**: The API key provided by Genlogs. This header must be included in the request.

### Endpoint

* **URL:** `https://api.genlogs.io/visual_sightings/carrier-observations`
* **`Method:`**` ``GET`

### Query Parameters

* **usdot\_number** (string, Required):  comma separated or single usdot for a specific carrier.
* **location\_city** (string, Optional):  city where data was captured.
* **location\_state** (string, Optional):  state where data was captured.
* **sighting\_start\_date** (string, Optional):  start date to make query.
* **sighting\_end\_date** (string, Optional):  end date to make query.&#x20;
* **page** (integer, Optional): Page number of results to return.
* **page\_size** (integer, Optional): Number of results per page.

### **Response**

* **200 OK:** A JSON object containing the message verified true or false
* **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:**

* **fmcsa\_detail** (array of `FMCSA` objects): Detail about the carrier in the search.
  * **usdot\_number**: (string) The USDOT number for the carrier.
  * **docket\_numbe**r: (string) The Motor Carrier number for carriers involved in interstate.
  * **legal\_name**: (string) The official registered name of the carrier.
  * **dba\_name**: (string)  The "Doing Business As" name, if applicable.
  * **carrier\_status**: (string) Indicates whether the carrier is active, inactive, or has a pending status.
  * **entity\_status**: (string) Refers to the legal standing of the carrier's business entity.
  * **carrier\_ein**: (string) It is a unique nine-digit number assigned by the IRS to identify the carrier for tax purposes.
  * **dun\_bradstreet\_no**: (string) It is a unique identifier assigned by Dun & Bradstreet to businesses.
  * **mcs150\_date**: (strin&#x67;**)** The date when the carrier last updated their MCS-150 form (Motor Carrier Identification Report).
  * **mcs150\_mileage**: (strin&#x67;**)** The total mileage reported by the carrier on their MCS-150 form, typically for the previous year.
  * **insurer\_company\_name**: (string)  The name of the insurance company providing coverage for the carrier.
  * **insurance\_docket\_number**: (string) A unique identifier for the insurance filing associated with the carrier.
  * **insurance\_policy\_number**: (strin&#x67;**)** The policy number assigned by the insurer to the carrier's insurance policy.
  * **insurance\_policy\_type**: (string) Specifies the type of insurance policy (e.g., liability, cargo, etc.).
  * **insurance\_form\_code**: (string) A code representing the type of insurance form filed (e.g., BMC-91 for liability insurance).
  * **insurance\_max\_coverage\_amount**: (string) The maximum coverage amount provided by the insurance policy.
  * **insurance\_underlying\_limit\_amount**: (string) The underlying limit amount, which is the base coverage before additional layers of insurance apply.
  * **insurance\_transaction\_date**: (string) The date when the insurance transaction (e.g., filing or update) was processed.
  * **insurance\_effective\_date**: (string) The start date of the insurance policy.
  * **insurance\_expiration\_date**: (string) The end date of the insurance policy.
  * **phy\_street:** (string) The street address of the carrier's physical location.
  * **phy\_city**: (string) The city where the carrier's physical address is located.
  * **phy\_state**: (string) The state where the carrier's physical address is located.
  * **phy\_zip**: (string) The ZIP code for the carrier's physical address.
  * **telephone**: (string) The carrier's primary contact phone number.
  * **email\_address**: (string) The carrier's email address for communication.
  * **mailing\_street**: (string) The street address of the carrier's mailing location.
  * **mailing\_city**: (string) The city where the carrier's mailing address is located.
  * **mailing\_state**: (string) The state where the carrier's mailing address is located.
  * **mailing\_zip**: (string) The ZIP code for the carrier's mailing address.
  * **mailing\_country**: (string) The country of the carrier's mailing address.
  * **carrier\_operation**: (string) Describes the type of operations the carrier is authorized to perform (e.g., interstate, intrastate, hazardous materials).
  * **operation\_classificiation**: (string) Specifies the classification of the carrier's operations, such as for-hire, private, exempt, or passenger.
  * **authority\_date**: (string) The date when the carrier's operating authority was granted.
  * **authorized\_for\_common\_date**: (string) The date when the carrier was authorized for common carrier operations.
  * **authorized\_for\_contract\_date**: (string) The date when the carrier was authorized for contract carrier operations.
  * **carrier\_total\_drivers**: (string) The total number of drivers employed by the carrier.
  * **carrier\_total\_power\_units**: (string) The total number of power units (e.g., trucks, tractors) operated by the carrier.
  * **carried\_cargo**: (string) The types of cargo the carrier is authorized to transport (e.g., general freight, hazardous materials).
  * **carrier\_driver\_insp**: (string) The total number of driver inspections conducted for the carrier.
  * **carrier\_driver\_oos\_insp**: (string) The number of driver inspections that resulted in an out-of-service (OOS) order.
  * **carrier\_driver\_oos\_rate**: (number) The percentage of driver inspections that resulted in an OOS order.
  * **carrier\_driver\_oos\_rate\_national\_avg**: (number) The national average OOS rate for drivers, used for comparison.
  * **carrier\_vehicle\_insp**: (string) The total number of vehicle inspections conducted for the carrier.
  * **carrier\_vehicle\_oos\_insp**: (string) The number of vehicle inspections that resulted in an OOS order.
  * **carrier\_vehicle\_oos\_rate**: (number) The percentage of vehicle inspections that resulted in an OOS order.
  * **carrier\_vehicle\_oos\_rate\_national\_avg**: (number) The national average OOS rate for vehicles, used for comparison.
  * **carrier\_hazmat\_insp**: (string) The total number of hazardous materials inspections conducted for the carrier.
  * **carrier\_hazmat\_oos\_insp**: (string) The number of hazardous materials inspections that resulted in an OOS order.
  * **carrier\_hazmat\_oos\_rate**: (number) The percentage of hazardous materials inspections that resulted in an OOS order.
  * **carrier\_hazmat\_oos\_rate\_national\_avg**: (number) The national average OOS rate for hazardous materials, used for comparison.
  * **carrier\_fatal\_crash**: (string) The total number of fatal crashes involving the carrier.
  * **carrier\_inj\_crash**: (string) The total number of crashes involving injuries for the carrier.
  * **carrier\_towaway\_crash**: (string)  The total number of crashes involving towaways for the carrier.&#x20;
  * **carrier\_crash\_total**: (string) The total number of crashes involving the carrier, including all types of crashes (fatal, injury, and towaway).
  * **recordable\_crash\_rate**: (number) The rate of recordable crashes per million vehicle miles traveled (VMT). This metric helps assess the carrier's safety performance.
  * **basic\_unsafe\_driving\_total\_violation**: (string) The total number of violations related to unsafe driving (e.g., speeding, reckless driving) recorded for the carrier.
  * **basic\_driver\_fitness\_total\_violation**: (string) The total number of violations related to driver fitness (e.g., invalid licenses, medical qualifications).
  * **basic\_hos\_total\_violation**: (string) The total number of violations related to Hours of Service (HOS) compliance (e.g., exceeding driving time limits, falsifying logs).
  * **basic\_drugs\_alcohol\_total\_violation**: (string) The total number of violations related to drug and alcohol use by drivers.
  * **basic\_vehicle\_maint\_total\_violation**: (string) The total number of violations related to vehicle maintenance (e.g., brake issues, lighting problems).
  * **carrier\_safety\_rating\_date**: (string) The date when the carrier's most recent safety rating was issued.
  *   **carrier\_safety\_rating**: (string)&#x20;

      The carrier's safety rating, which can be one of the following:

      * **Satisfactory**: Meets safety standards.
      * **Conditional**: Does not meet all safety standards but is allowed to operate.
      * **Unsatisfactory**: Fails to meet safety standards and is not allowed to operate.
  * **carrier\_safety\_review\_date**: (string)  The date when the carrier's most recent safety review was conducted.
  * **carrier\_safety\_review\_type**: (string) The type of safety review conducted (e.g., compliance review, safety audit).
* **observations** (array of `Observations` objects): List of observations for the search.&#x20;
  * **alpr\_plate\_number**: (string) License plate number captured by ALPR.
  * **usdot\_number**: (string) The USDOT number for the carrier.
  * **time\_captured**: (string) The timestamp when the data was captured.
  * **mc\_number**: (string) Motor Carrier number for the carrier.
  * **vin**: (string) Vehicle Identification Number.
  * **cab\_number**: (string) Cab number.
  * **equipment\_type**: (string). Type of equipment. Ie (Reefer, dryvan, etc.)
  * **equipment\_number**: (string). Number of the equipment.
  * **equipment\_logo**: (string) The logo of the trailer company.
  * **location\_city**: (string) City or county where the observation occurred. If observation is from FMCSA, it would be county. Otherwise will be a city.
  * **location\_state**: (string) State where the observation occurred.
  * **latitude**: (number), Latitude of the location where the observation occurred.
  * **longitude**: (number) , Longitude of the location where the observation occurred.
  * **route**: (string) Route and direction of travel.
  * **source**: (string) Source of the observation.
* **pagination**: Pagination metadata about the returned results.
  * **page** (integer): The current page number returned.
  * **page\_size** (integer): Number of results per page.
  * **results\_returned** (integer): Number of results returned in the current response.
  * **has\_more** (boolean): Indicates if more results are available.
  * **total** (integer): Total number of records matching the query.
  * **total\_pages** (integer): Total number of pages available.

### Response body for multiple USDOT searches:

* **carriers**: List of multiple USDOT information
  * **fmcsa\_detail** (array of `FMCSA` objects): Detail about the carrier in the search.
  * **observations** (array of `Observations` objects): List of observations for the search.
* **pagination**: Pagination metadata about the returned results.
  * **page** (integer): The current page number returned.
  * **page\_size** (integer): Number of results per page.

### Request Example:

```
curl -X GET 'https://api.genlogs.io/visual_sightings/carrier-observations?usdot_number=3481976,40717&location_city=enfield&location_state=NC' \
-H 'Access-Token: {access_token}' \
-H 'x-api-key: {your_api_key}' \
-i
```

## Carrier Observation

> Provide as a commercial auto insurance provider, access carrier sightings and operational insights.

OpenAPI:

```json
{"openapi":"3.1.0","info":{"title":"Visual Sightings API","version":"1.0.0"},"paths":{"/carrier-observations":{"get":{"tags":["sightings"],"summary":"Carrier Observation","description":"Provide as a commercial auto insurance provider, access carrier sightings and operational insights.","operationId":"carrier_observation_carrier_observations_get","parameters":[{"name":"usdot_number","in":"query","required":true,"schema":{"type":"string","description":"USDOT number to filter data for a specific carrier","title":"Usdot Number"},"description":"USDOT number to filter data for a specific carrier"},{"name":"location_city","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by city where data was captured","default":"","title":"Location City"},"description":"Filter by city where data was captured"},{"name":"location_state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by state where data was captured","default":"","title":"Location State"},"description":"Filter by state where data was captured"},{"name":"sighting_start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by start date","default":"","title":"Sighting Start Date"},"description":"Filter by start date"},{"name":"sighting_end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by end date","default":"","title":"Sighting End Date"},"description":"Filter by end date"},{"name":"last_seen_image","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Include last seen image information","default":false,"title":"Last Seen Image"},"description":"Include last seen image information"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (starting from 1)","default":1,"title":"Page"},"description":"Page number (starting from 1)"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Number of results per page (max 200)","default":100,"title":"Page Size"},"description":"Number of results per page (max 200)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"ListCarrierObservationResponseSchema","required":["data","pagination"],"properties":{"data":{"type":"object","properties":{"fmcsa_detail":{"type":"array","items":{"properties":{"usdot_number":{"type":"string","title":"Usdot Number","default":"55773"},"docket_number":{"type":"string","title":"Docket Number","default":"mc2580"},"legal_name":{"type":"string","title":"Legal Name","default":"CRST EXPEDITED INC"},"dba_name":{"type":"string","title":"Dba Name","default":"CRST THE TRANSPORTATION SOLUTION INC"},"carrier_status":{"type":"string","title":"Carrier Status","default":"Active"},"entity_type":{"type":"string","title":"Entity Type","default":"Carrier, Broker"},"carrier_ein":{"type":"string","title":"Carrier Ein","default":"420750182"},"dun_bradstreet_no":{"type":"string","title":"Dun Bradstreet No","default":"7793383"},"mcs150_date":{"type":"string","title":"Mcs150 Date","default":"2025-01-23"},"mcs150_mileage":{"type":"string","title":"Mcs150 Mileage","default":"2022"},"insurer_company_name":{"type":"string","title":"Insurer Company Name","default":"SELF-INSURED"},"insurance_docket_number":{"type":"string","title":"Insurance Docket Number","default":"MC1235"},"insurance_policy_number":{"type":"string","title":"Insurance Policy Number","default":"NA"},"insurance_policy_type":{"type":"string","title":"Insurance Policy Type","default":"BIPD/Primary"},"insurance_form_code":{"type":"string","title":"Insurance Form Code","default":"91X"},"insurance_max_coverage_amount":{"type":"string","title":"Insurance Max Coverage Amount","default":"1000000"},"insurance_underlying_limit_amount":{"type":"string","title":"Insurance Underlying Limit Amount","default":"0"},"insurance_transaction_date":{"type":"string","title":"Insurance Transaction Date","default":"2002-09-05"},"insurance_effective_date":{"type":"string","title":"Insurance Effective Date","default":"2002-10-01"},"insurance_expiration_date":{"type":"string","title":"Insurance Expiration Date","default":"2003-10-01"},"phy_street":{"type":"string","title":"Phy Street","default":"3930 16TH AVE SW"},"phy_city":{"type":"string","title":"Phy City","default":"CEDAR RAPIDS"},"phy_state":{"type":"string","title":"Phy State","default":"IA"},"phy_zip":{"type":"string","title":"Phy Zip","default":"52404"},"telephone":{"type":"string","title":"Telephone","default":"3193964400"},"email_address":{"type":"string","title":"Email Address","default":"rmorris@crst.com"},"mailing_street":{"type":"string","title":"Mailing Street","default":"PO BOX 68"},"mailing_city":{"type":"string","title":"Mailing City","default":"CEDAR RAPIDS"},"mailing_state":{"type":"string","title":"Mailing State","default":"IA"},"mailing_zip":{"type":"string","title":"Mailing Zip","default":"52406"},"mailing_country":{"type":"string","title":"Mailing Country","default":"US"},"carrier_operation":{"type":"string","title":"Carrier Operation","default":"Interstate"},"operation_classificiation":{"type":"string","title":"Operation Classificiation","default":"OTHER-GENERAL FREIGHT (EXCEPT HOUSEHOLD GOODS) | AUTHORIZED FOR HIRE"},"authority_date":{"type":"string","title":"Authority Date","default":"1992-10-21"},"authorized_for_common_date":{"type":"string","title":"Authorized For Common Date","default":"2011-10-26"},"authorized_for_contract_date":{"type":"string","title":"Authorized For Contract Date","default":"1992-10-21"},"carrier_total_drivers":{"type":"string","title":"Carrier Total Drivers","default":"3785"},"carrier_total_power_units":{"type":"string","title":"Carrier Total Power Units","default":"4050"},"carried_cargo":{"type":"string","title":"Carried Cargo","default":"General Freight | Metal: sheets, coils, rolls | etc."},"carrier_driver_insp":{"type":"string","title":"Carrier Driver Insp","default":"6830"},"carrier_driver_oos_insp":{"type":"string","title":"Carrier Driver Oos Insp","default":"45"},"carrier_driver_oos_rate":{"type":"number","title":"Carrier Driver Oos Rate","default":0.66},"carrier_driver_oos_rate_national_avg":{"type":"number","title":"Carrier Driver Oos Rate National Avg","default":5.51},"carrier_vehicle_insp":{"type":"string","title":"Carrier Vehicle Insp","default":"4365"},"carrier_vehicle_oos_insp":{"type":"string","title":"Carrier Vehicle Oos Insp","default":"818"},"carrier_vehicle_oos_rate":{"type":"number","title":"Carrier Vehicle Oos Rate","default":18.74},"carrier_vehicle_oos_rate_national_avg":{"type":"number","title":"Carrier Vehicle Oos Rate National Avg","default":20.72},"carrier_hazmat_insp":{"type":"string","title":"Carrier Hazmat Insp","default":"71"},"carrier_hazmat_oos_insp":{"type":"string","title":"Carrier Hazmat Oos Insp","default":"1"},"carrier_hazmat_oos_rate":{"type":"number","title":"Carrier Hazmat Oos Rate","default":1.41},"carrier_hazmat_oos_rate_national_avg":{"type":"number","title":"Carrier Hazmat Oos Rate National Avg","default":4.5},"carrier_fatal_crash":{"type":"string","title":"Carrier Fatal Crash","default":"8"},"carrier_inj_crash":{"type":"string","title":"Carrier Inj Crash","default":"97"},"carrier_towaway_crash":{"type":"string","title":"Carrier Towaway Crash","default":"198"},"carrier_crash_total":{"type":"string","title":"Carrier Crash Total","default":"303"},"recordable_crash_rate":{"type":"number","title":"Recordable Crash Rate","default":0},"basic_unsafe_driving_total_violation":{"type":"string","title":"Basic Unsafe Driving Total Violation","default":"594"},"basic_driver_fitness_total_violation":{"type":"string","title":"Basic Driver Fitness Total Violation","default":"81"},"basic_hos_total_violation":{"type":"string","title":"Basic Hos Total Violation","default":"234"},"basic_drugs_alcohol_total_violation":{"type":"string","title":"Basic Drugs Alcohol Total Violation","default":"8"},"BASIC_VEHICLE_MAINT_TOTAL_VIOLATION":{"type":"string","title":"Basic Vehicle Maint Total Violation","default":"2478"},"carrier_safety_rating_date":{"type":"string","title":"Carrier Safety Rating Date","default":"2014-05-23"},"carrier_safety_rating":{"type":"string","title":"Carrier Safety Rating","default":"Satisfactory"},"carrier_safety_review_date":{"type":"string","title":"Carrier Safety Review Date","default":"2024-12-16"},"carrier_safety_review_type":{"type":"string","title":"Carrier Safety Review Type","default":"New Entrant"}},"type":"object","title":"CarrierDetailsResponseSchema"}},"observations":{"type":"array","items":{"properties":{"alpr_plate_number":{"type":"string","title":"Alpr Plate Number","default":"p760855"},"usdot_number":{"type":"string","title":"Usdot Number","default":"3481976"},"time_captured":{"type":"string","title":"Time Captured","default":"2024-06-05T20:28:06Z"},"mc_number":{"type":"string","title":"Mc Number","default":"mc758629"},"vin":{"type":"string","title":"Vin","default":"vincn556288"},"cab_number":{"type":"string","title":"Cab Number","default":"56288"},"equipment_type":{"type":"string","title":"Equipment Type","default":"Reefer"},"equipment_number":{"type":"string","title":"Equipment Number","default":"123"},"equipment_logo":{"type":"string","title":"Equipment Logo","default":"Pepsi"},"location_city":{"type":"string","title":"Location City","default":"enfield"},"location_state":{"type":"string","title":"Location State","default":"NC"},"latitude":{"type":"number","title":"Latitude","default":4.56},"longitude":{"type":"number","title":"Longitude","default":-84.36},"route":{"type":"string","title":"Route","default":"95sb"},"source":{"type":"string","title":"Source","default":"genlogs"}},"type":"object","title":"CarrierObservationsResponseSchema"}}}},"pagination":{"type":"object","title":"Pagination","required":["page","page_size","results_returned","has_more","total","total_pages"],"properties":{"page":{"type":"integer","description":"The current page number"},"page_size":{"type":"integer","description":"The number of results per page"},"results_returned":{"type":"integer","description":"Number of results returned in the current response"},"has_more":{"type":"boolean","description":"Indicates if more results are available"},"total":{"type":"integer","description":"Total number of records matching the query"},"total_pages":{"type":"integer","description":"Total number of pages available"}}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}}}}
```
