NMFC Classification - API Docs

POST /api/search

Search Articles

Full-text search across NMFC articles by keyword, item number, or description fragment. Returns paginated results sorted by relevance.

Request Body

Parameter	Type	Description
`q` required	`string`	Search query. Minimum 3 characters. Matches article number, description, and grouping name.
`page` optional	`number`	Page number for pagination. Defaults to 1.

Response Fields

Field	Type	Description
`results`	`array`	Array of matching article objects
`total`	`number`	Total number of matching articles
`page`	`number`	Current page number
`totalPages`	`number`	Total number of pages
`results[].article_number`	`string`	NMFC article number
`results[].description`	`string`	Article description
`results[].grouping_name`	`string`	Commodity grouping name
`results[].classification`	`string`	Freight classification (e.g., "50", "55", "70")
`results[].is_canceled`	`boolean`	Whether the article has been canceled

Code Examples

curl -X POST https://freightapis.dev/api/search \
  -H "Authorization: Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"q": "frozen food", "page": 1}'

const response = await fetch('https://freightapis.dev/api/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ q: 'frozen food', page: 1 }),
});

const data = await response.json();
// data.results, data.total, data.page, data.totalPages

import requests

response = requests.post(
    'https://freightapis.dev/api/search',
    headers={'Authorization': 'Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx'},
    json={'q': 'frozen food', 'page': 1},
)

data = response.json()
# data['results'], data['total'], data['page'], data['totalPages']

{
  "article": {
    "articles": [
      {
        "article_number": "63321",
        "description": "Televisions (TVs) or Video, Computer or Multimedia Monitors or Displays, NOI, see Note, item 63324, in boxes or Packages 829, 979, 2320 or 2396:",
        "grouping_name": "ELECTRICAL EQUIPMENT GROUP",
        "classification": "",
        "is_canceled": 0
      }
    ],
    "totalMatch": 3
  },
  "totalPages": 1,
  "currentPage": 1,
  "success": true
}

GET /api/article/:num

Get Article

Retrieve complete article data for a single NMFC article, including all sub-items, density classifications, hazardous flags, and cross-reference notes.

URL Parameters

Parameter	Type	Description
`num` required	`string`	NMFC article number (e.g., 63321). Include only the base number, not the sub-item suffix.

Response Fields

Field	Type	Description
`article_number`	`string`	NMFC article number
`description`	`string`	Full article description
`grouping_name`	`string`	Commodity grouping name
`classification`	`string`	Freight class when no sub-items are present
`is_hazardous`	`boolean`	Whether the article is classified as hazardous material
`is_special_handling`	`boolean`	Whether the article requires special handling
`is_canceled`	`boolean`	Whether the article has been canceled
`canceled_reference`	`string \| null`	Replacement article number, if canceled
`note_references`	`string[]`	Array of note identifiers that apply to this article
`tariff_issue`	`string`	Tariff issue number that introduced or last modified this article
`supplement`	`string \| null`	Supplement identifier, if applicable
`subItems`	`array`	List of sub-item objects (see below)
`subItems[].item`	`string`	Sub-item suffix (e.g., "00", "01")
`subItems[].description`	`string`	Sub-item description detailing density or packaging conditions
`subItems[].classification`	`string`	Freight class for this sub-item
`subItems[].sort_order`	`number`	Display ordering index

Code Examples

curl https://freightapis.dev/api/article/63321 \
  -H "Authorization: Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx"

const response = await fetch('https://freightapis.dev/api/article/63321', {
  headers: {
    'Authorization': 'Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx',
  },
});

const article = await response.json();
// article.article_number, article.subItems[], ...

import requests

response = requests.get(
    'https://freightapis.dev/api/article/63321',
    headers={'Authorization': 'Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx'},
)

article = response.json()

{
  "success": true,
  "article": {
    "articleNumber": "63321",
    "description": "Televisions (TVs) or Video, Computer or Multimedia Monitors or Displays, NOI, see Note, item 63324, in boxes or Packages 829, 979, 2320 or 2396:",
    "grouping": "ELECTRICAL EQUIPMENT GROUP",
    "subGrouping": null,
    "tariffIssue": "AY",
    "supplement": "1",
    "classification": "",
    "isHazardous": false,
    "isSpecialHandling": true,
    "isCanceled": false,
    "canceledReference": null,
    "noteReferences": ["63324"],
    "articleSubItems": [
      { "item": "Sub 1", "description": "In authorized packages as specified in Note, item 63322, subject to Item 170 and having a density in pounds per cubic foot of:", "classification": "" },
      { "item": "Sub 2", "description": "Less than 4", "classification": "400" },
      { "item": "Sub 3", "description": "4 but less than 8", "classification": "175" },
      { "item": "Sub 4", "description": "8 or greater", "classification": "110" },
      { "item": "Sub 5", "description": "In authorized packages other than as specified in Note, item 63322, subject to Item 170 and having a density in pounds per cubic foot of:", "classification": "" },
      { "item": "Sub 6", "description": "Less than 4", "classification": "300" },
      { "item": "Sub 7", "description": "4 but less than 8", "classification": "150" },
      { "item": "Sub 8", "description": "8 or greater", "classification": "100" }
    ]
  }
}

GET /api/rule/:num

Get Rule

Retrieve the full text of a single NMFC rule by its rule number, including all sub-headings and structured description blocks.

URL Parameters

Parameter	Type	Description
`num` required	`string`	NMFC rule number (3–6 characters, e.g., 100). Must match a valid rule in the tariff.

Response Fields

Field	Type	Description
`success`	`boolean`	Indicates whether the request succeeded
`rule`	`object`	The rule object
`rule.ruleNumber`	`string`	NMFC rule number
`rule.ruleHeader`	`string`	Short title / header of the rule
`rule.ruleSubHeading`	`string`	Secondary heading providing additional context
`rule.ruleDescriptions`	`array`	Ordered list of description blocks
`rule.ruleDescriptions[].type`	`string`	Block type identifier (e.g., "paragraph", "list")
`rule.ruleDescriptions[].title`	`string`	Optional title for the block
`rule.ruleDescriptions[].text`	`string`	Full text content of the block

Code Examples

curl https://freightapis.dev/api/rule/100 \
  -H "Authorization: Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx"

const response = await fetch('https://freightapis.dev/api/rule/100', {
  headers: {
    'Authorization': 'Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx',
  },
});

const data = await response.json();
// data.rule.ruleNumber, data.rule.ruleDescriptions[], ...

import requests

response = requests.get(
    'https://freightapis.dev/api/rule/100',
    headers={'Authorization': 'Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx'},
)

data = response.json()
# data['rule']['ruleNumber'], data['rule']['ruleDescriptions'], ...

{
  "success": true,
  "rule": {
    "ruleNumber": "110",
    "ruleHeader": "",
    "ruleSubHeading": null,
    "ruleDescriptions": [
      {
        "type": "generic",
        "title": "",
        "text": "The following definitions will apply when such terms are used in this Classification..."
      },
      {
        "type": "sec",
        "title": "Sec. 1.",
        "text": "'Carrier,' 'Consignee,' 'Consignor' or 'Shipper' includes the authorized representatives or agents..."
      },
      {
        "type": "sec",
        "title": "Sec. 8. (a)",
        "text": "To determine the density of a handling unit, first determine the cubage..."
      }
    ]
  }
}

GET /api/package/:num

Get Package

Retrieve the full details of a single NMFC package definition by its package number, including the applicable tariff issue and all structured description blocks.

URL Parameters

Parameter	Type	Description
`num` required	`string`	NMFC package number (2–6 characters, e.g., 10). Must match a valid package in the tariff.

Response Fields

Field	Type	Description
`success`	`boolean`	Indicates whether the request succeeded
`package`	`object`	The package object
`package.packageNumber`	`string`	NMFC package number
`package.packageHeader`	`string`	Short title / header of the package definition
`package.tariffIssue`	`string`	Tariff issue number that introduced or last modified this package
`package.packageDescriptions`	`array`	Ordered list of description blocks
`package.packageDescriptions[].type`	`string`	Block type identifier (e.g., "paragraph", "list")
`package.packageDescriptions[].title`	`string`	Optional title for the block
`package.packageDescriptions[].text`	`string`	Full text content of the block

Code Examples

curl https://freightapis.dev/api/package/10 \
  -H "Authorization: Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx"

const response = await fetch('https://freightapis.dev/api/package/10', {
  headers: {
    'Authorization': 'Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx',
  },
});

const data = await response.json();
// data.package.packageNumber, data.package.packageDescriptions[], ...

import requests

response = requests.get(
    'https://freightapis.dev/api/package/10',
    headers={'Authorization': 'Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx'},
)

data = response.json()
# data['package']['packageNumber'], data['package']['packageDescriptions'], ...

{
  "success": true,
  "package": {
    "packageNumber": "829",
    "packageHeader": "Package 829",
    "tariffIssue": "AY",
    "packageDescriptions": [
      {
        "type": "description",
        "title": "",
        "text": "In fiberboard boxes complying with Item 222..."
      }
    ]
  }
}

GET /api/history/:num

Get Article Change History

Retrieve the complete change history for a single NMFC article, including every docket, issued date, subject line, and granular change detail records.

URL Parameters

Parameter	Type	Description
`num` required	`string`	NMFC article number (3–10 characters, e.g., 63321). Include only the base number, not the sub-item suffix.

Response Fields

Field	Type	Description
`success`	`boolean`	Indicates whether the request succeeded
`articleNumber`	`string`	The queried NMFC article number
`articleChangeHistoryDetails`	`array`	Ordered list of change history entries
`articleChangeHistoryDetails[].docket`	`string`	Docket identifier associated with this change
`articleChangeHistoryDetails[].issuedDate`	`string`	ISO 8601 date the change was issued
`articleChangeHistoryDetails[].subject`	`string`	Short description of the change subject
`articleChangeHistoryDetails[].quickView`	`string`	One-line summary of the change for display purposes
`articleChangeHistoryDetails[].changeDetails`	`array`	Granular list of individual changes within this entry
`articleChangeHistoryDetails[].changeDetails[].description`	`string`	Narrative description of the individual change
`articleChangeHistoryDetails[].changeDetails[].typeOfProvision`	`string`	Category of provision affected (e.g., "Item", "Note")
`articleChangeHistoryDetails[].changeDetails[].item`	`string`	Primary item identifier affected by the change
`articleChangeHistoryDetails[].changeDetails[].alternateItem`	`string`	Alternate or replacement item number, if applicable
`articleChangeHistoryDetails[].changeDetails[].action`	`string`	Type of action taken (e.g., "Added", "Amended", "Canceled")

Code Examples

curl https://freightapis.dev/api/history/63321 \
  -H "Authorization: Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx"

const response = await fetch('https://freightapis.dev/api/history/63321', {
  headers: {
    'Authorization': 'Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx',
  },
});

const data = await response.json();
// data.articleNumber, data.articleChangeHistoryDetails[], ...

import requests

response = requests.get(
    'https://freightapis.dev/api/history/63321',
    headers={'Authorization': 'Bearer nmfc_live_xxxxxxxxxxxxxxxxxxxx'},
)

data = response.json()
# data['articleNumber'], data['articleChangeHistoryDetails'], ...

{
  "success": true,
  "articleNumber": "63321",
  "articleChangeHistoryDetails": [
    {
      "docket": "2024-2",
      "issuedDate": "2024-05-15",
      "subject": "1",
      "quickView": "Classification amended",
      "changeDetails": [
        {
          "description": "Sub-item classifications updated",
          "typeOfProvision": "Article",
          "item": "63321",
          "alternateItem": "",
          "action": "Amend"
        }
      ]
    }
  ]
}

POST /api/density

Density Calculator

Calculate freight density from dimensions and weight. Supports multiple handling units, various dimension units (Inch, Feet, Centimeter, Meter), and weight units (Pound, Kilogram).

Request Body

Parameter	Type	Required
`dimensionType` required	`string`	Inch, Feet, Centimeter, or Meter
`weightType` required	`string`	Pound or Kilogram
`resultUnitType` required	`string`	PoundsPerCubicFeet or KilogramPerCubicMeter
`unitDimensions` required	`array`	Array of unit dimension objects
`unitDimensions[].HandlingUnitCount` required	`number`	Number of identical handling units
`unitDimensions[].length` required	`number`	Length in specified dimension unit
`unitDimensions[].width` required	`number`	Width in specified dimension unit
`unitDimensions[].height` required	`number`	Height in specified dimension unit
`unitDimensions[].handlingUnitWeight` required	`number`	Total weight of all units combined

Response

Field	Type	Description
`totalHandlingUnitCount`	`number`	Sum of all handling unit counts
`totalHandlingUnitCountVolume`	`number`	Total volume in result units
`totalHandlingUnitWeight`	`number`	Total weight in result units
`totalDensity`	`number`	Overall density (weight / volume)
`unitDimensions[]`	`array`	Per-unit breakdown with volume and density

Examples

curl -X POST https://freightapis.dev/api/density \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensionType": "Inch",
    "weightType": "Pound",
    "resultUnitType": "PoundsPerCubicFeet",
    "unitDimensions": [{
      "HandlingUnitCount": 1,
      "length": 48, "width": 40, "height": 36,
      "handlingUnitWeight": 500
    }]
  }'

const response = await fetch('https://freightapis.dev/api/density', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dimensionType: 'Inch',
    weightType: 'Pound',
    resultUnitType: 'PoundsPerCubicFeet',
    unitDimensions: [{
      HandlingUnitCount: 1,
      length: 48, width: 40, height: 36,
      handlingUnitWeight: 500,
    }],
  }),
});

const data = await response.json();
// data.totalDensity, data.unitDimensions[], ...

import requests

response = requests.post(
    'https://freightapis.dev/api/density',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'dimensionType': 'Inch',
        'weightType': 'Pound',
        'resultUnitType': 'PoundsPerCubicFeet',
        'unitDimensions': [{
            'HandlingUnitCount': 1,
            'length': 48, 'width': 40, 'height': 36,
            'handlingUnitWeight': 500,
        }],
    },
)

data = response.json()
# data['totalDensity'], data['unitDimensions'], ...

{
  "success": true,
  "unitDimensions": [
    {
      "handlingUnitCount": 1,
      "length": 48, "width": 40, "height": 36,
      "handlingUnitCountVolume": 40,
      "handlingUnitWeight": 500,
      "density": 12.5
    }
  ],
  "totalHandlingUnitCount": 1,
  "totalHandlingUnitCountVolume": 40,
  "totalHandlingUnitWeight": 500,
  "totalDensity": 12.5
}

POST /api/item680/:type

Item 680 Calculator

NMFC Item 680 Note calculators for determining freight class by volume, area, or dimension ratio. Three calculator types available: 2a (Volume), 2b (Area), 2c (Ratio).

URL Parameter

Type	Endpoint	Description
2a	POST /api/item680/2a	Volume: commodity vs package volume comparison
2b	POST /api/item680/2b	Area: commodity vs handling platform area comparison
2c	POST /api/item680/2c	Ratio: height to shortest dimension ratio calculation

Note 2A Request Body (Volume)

Parameter	Type	Description
`commodity.length` required	`number`	Commodity length
`commodity.width` required	`number`	Commodity width
`commodity.height` required	`number`	Commodity height
`package.length` required	`number`	Package length
`package.width` required	`number`	Package width
`package.height` required	`number`	Package height

Response: commodityVolume, packageVolume, percentageVolumeOccupiedByCommodity, isBelowThreshold

Note 2B Request Body (Area)

Parameter	Type	Description
`commodity.length` required	`number`	Commodity length
`commodity.width` required	`number`	Commodity width
`handlingPlatformType.length` required	`number`	Platform length
`handlingPlatformType.width` required	`number`	Platform width

Response: commodityArea, liftArea, percentageSurfaceAreaOccupiedByCommodity, isBelowThreshold

Note 2C Request Body (Ratio)

Parameter	Type	Description
`length` required	`number`	Commodity length
`width` required	`number`	Commodity width (shortest dimension)
`height` required	`number`	Commodity height
`liftLength` required	`number`	Lift platform length
`liftWidth` required	`number`	Lift platform width

Response: ratio, isAboveThreshold, maximumAllowableCalculations

Examples

# Note 2A — Volume comparison
curl -X POST https://freightapis.dev/api/item680/2a \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commodity": {"length": 46, "width": 40, "height": 330},
    "package": {"length": 48, "width": 40, "height": 35}
  }'

# Note 2B — Area comparison
curl -X POST https://freightapis.dev/api/item680/2b \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commodity": {"length": 38, "width": 32},
    "handlingPlatformType": {"length": 40, "width": 40}
  }'

# Note 2C — Dimension ratio
curl -X POST https://freightapis.dev/api/item680/2c \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"length":50,"width":42,"height":62,"liftLength":52,"liftWidth":45}'

// Note 2A — Volume comparison
const res2a = await fetch('https://freightapis.dev/api/item680/2a', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    commodity: { length: 46, width: 40, height: 330 },
    package: { length: 48, width: 40, height: 35 },
  }),
});

// Note 2B — Area comparison
const res2b = await fetch('https://freightapis.dev/api/item680/2b', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    commodity: { length: 38, width: 32 },
    handlingPlatformType: { length: 40, width: 40 },
  }),
});

// Note 2C — Dimension ratio
const res2c = await fetch('https://freightapis.dev/api/item680/2c', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ length: 50, width: 42, height: 62, liftLength: 52, liftWidth: 45 }),
});

import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}

# Note 2A — Volume comparison
res2a = requests.post('https://freightapis.dev/api/item680/2a', headers=headers, json={
    'commodity': {'length': 46, 'width': 40, 'height': 330},
    'package': {'length': 48, 'width': 40, 'height': 35},
})

# Note 2B — Area comparison
res2b = requests.post('https://freightapis.dev/api/item680/2b', headers=headers, json={
    'commodity': {'length': 38, 'width': 32},
    'handlingPlatformType': {'length': 40, 'width': 40},
})

# Note 2C — Dimension ratio
res2c = requests.post('https://freightapis.dev/api/item680/2c', headers=headers, json={
    'length': 50, 'width': 42, 'height': 62, 'liftLength': 52, 'liftWidth': 45,
})

// 2A — Volume response
{
  "success": true,
  "commodityVolume": 607200,
  "packageVolume": 67200,
  "percentageVolumeOccupiedByCommodity": 903.57,
  "isBelowThreshold": false
}