# US Trade Data Scraper - Comtrade & Census Aggregates

Collect country and commodity trade aggregates from keyless UN Comtrade preview, plus optional Census import data with your key. Source links and status included. No shipment or consignee records.

Canonical product page: https://mayd-it.com/data-tools/actors/us-import-trade-bol-scraper/
Public Actor: https://apify.com/maydit/us-import-trade-bol-scraper

## Example input

```json
{
  "sources": [
    "comtrade"
  ],
  "reporterCode": "842",
  "flowCode": "M",
  "cmdCode": "TOTAL",
  "partnerCode": "0",
  "hsCode": "85",
  "maxItems": 10,
  "maxRunSeconds": 240,
  "softFail": false
}
```

## Full guide

![Explore public trade aggregates — illustrative workflow](https://api.apify.com/v2/key-value-stores/YGxD9JRpduom8Q5Zd/records/us-import-trade-bol-scraper-8c0073e5aaea.png?signature=zRx4WpMC1OCmDpEfLMyx)

## Explore public trade aggregates

For trade researchers, collect commodity and country aggregates from public statistical sources without treating them as shipment records.

**Coverage:** Keyless UN Comtrade preview by default. Optional Census HS import aggregates require a free Census API key. No bills of lading are returned.

[Open this Actor in Console](https://console.apify.com/actors/FSfp9bNavLJBfY9rX/input) · [First run](#try-this-actor) · [Results](#result-preview) · [Cost](#usage-and-pricing) · [Full guide](#full-guide)

## Try this Actor

1. Use the existing Comtrade defaults and keep the maximum saved-row cap small. Add Census only after supplying its required key.
2. Review aggregate rows in the run's dataset and read `SUMMARY` for source status, completeness and stop reasons.

**Read the results correctly:** These rows do not identify individual shipments, importers or consignees. With soft-fail enabled, a successful run can still contain no collected data.

## Result preview

The dataset view highlights these columns:

- **Aggregate record type** · `recordType`
- **Commodity code** · `commodityCode`
- **Reported trade partner** · `partner`
- **Reporting period** · `period`
- **Reported trade value** · `value`
- **Statistical source** · `source`

Use the original source links and the field definitions below when interpreting the results. CSV works well for flat columns; JSON preserves nested values.

## Usage and pricing

Base result rate on the FREE tier: **$3 per 1,000 results**. The [Pricing tab](https://apify.com/maydit/us-import-trade-bol-scraper/pricing) shows your plan's result rate and any Actor Start charge. Set a small result limit for the first run; the requested limit is not a guarantee of that many results.

---

## Full guide

> **Honest scope:** this Actor returns **public trade aggregates**, not bills of lading.
> Default source is **UN Comtrade public preview** (keyless). Optional **Census Bureau** HS
> import aggregates need a free Census API key. True BOL / ImportYeti-class scrapers are
> outside this Actor’s supported scope.

### Defaults (no paid keys)

| Input | Default | Behavior |
|---|---|---|
| `sources` | `["comtrade"]` | Keyless UN Comtrade preview |
| `reporterCode` | `842` (USA) | Comtrade reporter |
| `cmdCode` | `TOTAL` | World aggregate; when `maxItems` > 1 also expands a few HS2 chapters |
| `censusApiKey` | empty | Census source skipped unless you supply a free key |

Without any key you still get real Comtrade aggregate row(s). Census is soft-fail / optional only.

### What you will **not** get

- Individual bills of lading, consignee lists, or vessel manifests
- ImportYeti / Panjiva / commercial BOL HTML scrapes

### Source failures

Complete source failure fails the run by default. Explicit `softFail: true` keeps the run successful with zero dataset rows and `SUMMARY.status = source_failed`; diagnostics are stored only in `SUMMARY`. A genuine empty query succeeds with an empty dataset and a warning.

### Result accounting

Only real source records are written to the dataset. `SUMMARY.total` counts saved rows. A dataset spending cap stops further writes and sets `SUMMARY.stoppedOnChargeLimit` and `SUMMARY.incomplete`. Source failures and time limits are reported in the summary; they do not generate substitute result rows.

## Help with your run

Open the **Issues** tab on this Actor with the run URL, the input field that caused trouble and what you expected to receive. Remove API keys and private information before posting.

[Explore more Mayd-It Actors](https://apify.com/maydit)

## Understand your run

Open **Run report** in the run’s Output tab for saved-record counts, reported source issues and limits, and suggested next steps. Use **CSV export** to take the saved results into a spreadsheet. The existing JSON results and detailed machine-readable summary remain available.

The report reflects this run’s recorded coverage. A successful run or a saved result does not establish that every possible source record was collected.