FMCSA REST API

Typed, ESM-first client for the FMCSA QCMobile API. The official FMCSA documentation only includes prose tables, so this SDK wraps the public endpoints with a strongly typed TypeScript interface, normalizes the JSON and adds ergonomic helpers for Node.js and modern browsers.

Installation

npm install fmcsa-sdk

The package targets native ESM and requires Node.js 18+ (or any runtime that provides a fetch implementation). For Node.js 16 you can pass a custom fetch (for example node-fetch).

Authentication

FMCSA uses a WebKey query parameter for all requests. Store yours in an environment variable so you never accidentally commit it:

# .env
FMCSA_WEBKEY=replace-with-your-key

FmcsaClient automatically reads FMCSA_WEBKEY, FMCSA_WEB_KEY or WEBKEY. You can also pass the value explicitly through the constructor options.

Usage

import { FmcsaClient } from 'fmcsa-sdk';

const client = new FmcsaClient({
  // Optional when FMCSA_WEBKEY is present in process.env
  // webKey: process.env.FMCSA_WEBKEY,
  userAgent: 'my-company/fmcsa-internal-tool',
});

const carriers = await client.searchCarriersByName('greyhound', { size: 10 });
carriers.data.forEach((carrier) => {
  console.log(carrier.dotNumber, carrier.legalName, carrier.allowToOperate);
});

const profile = await client.getCarrierByDot(44110);
console.log(profile.data?.phyCity, profile.data?.telephone);

const basics = await client.getCarrierBasics(44110);
basics.data.forEach((basic) => console.log(basic.basicShortDesc, basic.percentile));

Every public method returns a NormalizedResponse<T> with:

• data – typed array/object for the requested endpoint.
• raw – the unmodified payload from FMCSA in case you need fields that are not modeled yet.
• Metadata such as retrievalDate, content (status text) and _links if FMCSA sends them.

Available helpers

| Method | Description | | --- | --- | | searchCarriersByName(name, { start, size }) | Search carriers by legal or DBA name. | | getCarrierByDot(dotNumber) | Fetch a single carrier profile by USDOT number. | | getCarrierByDocketNumber(docketNumber) | Fetch a profile using an MC/MX docket number. | | getCarrierBasics(dotNumber) | Retrieve BASIC measurements for a carrier. | | getCargoCarried(dotNumber) | Cargo categories reported by the carrier. | | getOperationClassifications(dotNumber) | Operation classifications published by FMCSA. | | getOutOfServiceOrders(dotNumber) | Planned support once FMCSA exposes the /oos endpoint. Currently throws an explanatory error. | | getDocketNumbers(dotNumber) | All docket numbers tied to the USDOT number. | | getAuthority(dotNumber) | Operating authority statuses. |

⚠️ FMCSA only documents these endpoints in prose. The SDK normalizes obvious nested lists (e.g. content[].carrier, content[].basic) but leaves the raw payload accessible so you can inspect additional fields as the agency evolves the API.

❗️ The carriers/:dotNumber/oos endpoint currently responds with “Webkey not found” even with valid credentials. The SDK keeps getOutOfServiceOrders as a placeholder that throws an explanatory error so consumers know the functionality is pending FMCSA access.

Error handling

• FmcsaSDKError – thrown for client side problems (missing webKey, failing to parse JSON, missing fetch, etc.).
• FmcsaApiError – thrown when FMCSA returns a non-2xx status. The instance exposes the HTTP status code and the parsed payload (when available).

Example:

try {
  await client.getCarrierByDot('0');
} catch (error) {
  if (error instanceof FmcsaApiError) {
    console.error(error.status, error.payload);
  }
}

Configuration

const client = new FmcsaClient({
  baseUrl: 'https://mobile.fmcsa.dot.gov/qc/services/',
  defaultParams: { size: 25 },
  fetch: customFetch,
  userAgent: 'acme/fmcsa-sdk'
});

• baseUrl lets you point the client at a mock server during tests.
• defaultParams are appended to every request (for example a default size).
• fetch allows you to bring your own fetch-compatible function in older runtimes.
• userAgent sets a friendly header for FMCSA logs.

Development

npm install
npm run typecheck
npm run build

Publishing is handled by npm's prepare hook so dist/ always stays in sync.

Sample payloads captured from the live FMCSA API live under /samples so you can inspect the raw schema without hitting the network.

Roadmap / ideas

1. Add higher level helpers that page through large carrier search results.
2. Remove the temporary error and implement getOutOfServiceOrders once FMCSA exposes the endpoint publicly.
3. Contribute a community-maintained OpenAPI document once FMCSA expands their docs (possibly using the /samples fixtures as a starting point).