groundtruth-tariff

Source-linked 2026 US tariff & landed-cost API for AI agents and ecommerce sellers.

Get accurate US import duties — MFN rates, Section 301/232 tariffs, MPF/HMF fees — and total landed cost in a single call. Every rate is traceable to an official source.

Install

npm install groundtruth-tariff

Quick start

const { calculateTariff } = require('groundtruth-tariff');

const result = await calculateTariff({
  product: 'cotton t-shirt',
  origin: 'CN',
  value: 1000
});

console.log(result);
// {
//   as_of: '2026-09-29',
//   origin: 'CN',
//   matched_category: { id: 'apparel', label: 'Apparel & clothing' },
//   duty_breakdown: [
//     { name: 'MFN duty', rate: 0.165 },
//     { name: 'Section 301', rate: 0.25 },
//     ...
//   ],
//   total_duty_rate: 0.54,
//   total_customs_duty: 540,
//   fees: { mpf: 34.65, hmf: 12.5 },
//   total_landed_cost: 1573.50,
//   sources: [ ... ]
// }

API

calculateTariff({ product, origin, value, mode })

Calculate import duty and full landed cost.

| Param | Type | Required | Description | |-------|------|----------|-------------| | product | string | ✅ | Product description, e.g. 'cotton t-shirt' | | origin | string | ✅ | Origin country code: CN, VN, IN, MX, etc. | | value | number | ✅ | Declared customs value in USD | | mode | string | ❌ | Shipping mode: 'ocean' (default) or 'air' |

Returns a promise resolving to the full duty breakdown, fees, and landed cost.

listCategories()

List all supported tariff categories, origin countries, and fee rules.

const { listCategories } = require('groundtruth-tariff');

const data = await listCategories();
console.log(data.categories);

Examples

Smartphone from Vietnam, shipped by air:

const result = await calculateTariff({
  product: 'smartphone',
  origin: 'VN',
  value: 2000,
  mode: 'air'
});

Error handling:

try {
  const result = await calculateTariff({ product: 'shoes', origin: 'CN', value: 500 });
} catch (err) {
  console.error('Tariff lookup failed:', err.message);
}

Why GroundTruth?

• 🔗 Source-linked — every rate points to an official source, no black-box guesses
• 🇺🇸 US-specific — MFN, Section 301 (China), Section 232 (steel/aluminum), forced-labor flags
• 📦 Landed cost, not just duty — includes MPF, HMF, and shipping-mode adjustments
• 🤖 Built for AI agents — also available over MCP
• 🔄 Always current — rates refresh automatically as policy changes

Free tools

• 🧮 Free tariff calculator: https://contentforge-press.github.io/groundtruth-calculator/
• 📚 API docs & pricing: https://dytsk9wrfv.page.coze.site/groundtruth.html

License

MIT © GroundTruth

Free tier includes attribution. Paid plans remove attribution and raise rate limits.