> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotlookup.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Carriers

> Paginated carrier search with text, filters, and geo/radius support

Paginated search with text, filters, and optional geo/radius support.

<Note>
  When using geo search (`lat`/`lon`), each result includes a `distance_miles` field with the distance from the search point.
</Note>

<Warning>
  **Geo resolution is state-level.** Every carrier in a state shares the same geocoded point — the centroid of that state. As a result:

  * A `radius` smaller than the diameter of a state will return very few or zero results.
  * Practical floor: **\~200 miles** to reliably hit carriers in neighboring states' centroids.
  * Use `state=XX` for tighter location filtering at the state level, or `city=...` for city-level filtering by name (string match on the carrier's physical address city).

  This is a limitation of the daily ETL's geocoding step, not a query bug. Real per-carrier geocoding is on the roadmap.
</Warning>

## Query Parameters

<ParamField query="q" type="string">
  Text search (matches legal name and DBA name)
</ParamField>

<ParamField query="mc_number" type="string">
  Filter by MC number. To resolve many MC numbers at once, use [Bulk Lookup by MC](/endpoints/bulk-lookup-mc) instead of looping this endpoint.
</ParamField>

<ParamField query="city" type="string">
  Filter by city
</ParamField>

<ParamField query="state" type="string">
  Filter by state (2-letter code)
</ParamField>

<ParamField query="status" type="string" default="ACTIVE">
  Filter by carrier status. Use `ALL` to include inactive carriers
</ParamField>

<ParamField query="cargo" type="string">
  Filter by cargo type
</ParamField>

<ParamField query="entity_type" type="string">
  Filter by entity type (e.g. `CARRIER`, `BROKER`, `FREIGHT FORWARDER`, `SHIPPER`)
</ParamField>

<ParamField query="officer" type="string">
  Filter by company officer name (matches either of the two officer slots)
</ParamField>

<ParamField query="phone" type="string">
  Filter by phone number
</ParamField>

<ParamField query="email" type="string">
  Filter by email address
</ParamField>

<ParamField query="fleet_min" type="integer">
  Minimum power units
</ParamField>

<ParamField query="fleet_max" type="integer">
  Maximum power units
</ParamField>

<ParamField query="lat" type="number">
  Latitude for geo search (requires `lon`)
</ParamField>

<ParamField query="lon" type="number">
  Longitude for geo search (requires `lat`)
</ParamField>

<ParamField query="radius" type="integer" default="50">
  Search radius in miles (max: 200)
</ParamField>

<ParamField query="authority_months_min" type="integer">
  Minimum months of active authority (filters by common authority date)
</ParamField>

<ParamField query="sort" type="string">
  Sort field and direction. Options: `name`, `name_asc`, `name_desc`, `dot`, `dot_asc`, `dot_desc`, `fleet_size`, `fleet_size_asc`, `fleet_size_desc`, `distance`, `distance_asc`, `distance_desc` (distance options require geo search)
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number
</ParamField>

<ParamField query="per_page" type="integer" default="25">
  Results per page (max: 100)
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.dotlookup.dev/v1/carriers/search?q=swift&state=TX&fleet_min=10"
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get("https://api.dotlookup.dev/v1/carriers/search", params={
      "q": "swift",
      "state": "TX",
      "fleet_min": 10,
  })
  results = resp.json()
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ q: "swift", state: "TX", fleet_min: "10" });
  const resp = await fetch(`https://api.dotlookup.dev/v1/carriers/search?${params}`);
  const results = await resp.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "dot_number": "2233855",
        "mc_number": "747866",
        "legal_name": "SWIFT TRANSPORTATION CO",
        "dba_name": "",
        "city": "Dallas",
        "state": "TX",
        "status": "ACTIVE",
        "entity_type": "CARRIER",
        "power_units": 45,
        "drivers": 52,
        "vehicle_oos_rate": 18.3,
        "vehicle_oos_national": 20.72,
        "driver_oos_rate": 5.2,
        "driver_oos_national": 5.51,
        "insurance_bipd": 1000000,
        "insurance_cargo": 250000,
        "lat": 32.7767,
        "lon": -96.797
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 1,
      "total_pages": 1
    }
  }
  ```
</ResponseExample>