Retrieve Census International Trade HS Year-to-Date Imports

Purpose

Retrieve Census International Trade imports data for an HTS code and month, preserving the API's year-to-date general-import and imports-for-consumption values.

When to Use

Use for aggregate or country-level U.S. imports queries against the Census International Trade HS timeseries endpoint when the caller supplies an HTS code and reporting period.

Workflow

1. Build the direct API URL; do not visit the Census homepage or use UI controls: https://api.census.gov/data/timeseries/intltrade/imports/hs?get=GEN_VAL_YR%2CCON_VAL_YR%2CI_COMMODITY%2CI_COMMODITY_LDESC%2CCTY_CODE%2CC_TY_NAME%2CLAST_UPDATE&time={year}-{month}&I_COMMODITY={hts-code}&CTY_CODE=- Use the correctly spelled field CTY_NAME in the actual request: get=GEN_VAL_YR%2CCON_VAL_YR%2CI_COMMODITY%2CI_COMMODITY_LDESC%2CCTY_CODE%2CCTY_NAME%2CLAST_UPDATE.
2. Navigate to that URL and, in the same browser call, run this evaluate() extractor on the loaded response:

   (() => {
     const text = (
       document.body?.innerText ||
       document.body?.textContent ||
       ""
     ).trim();
     let data;
     try {
       data = JSON.parse(text);
     } catch (_) {
       return { columns: [], rows: [] };
     }
     if (!Array.isArray(data) || data.length === 0 || !Array.isArray(data[0])) {
       return { columns: [], rows: [] };
     }
     const columns = data[0];
     const rows = data
       .slice(1)
       .map((row) =>
         Object.fromEntries(
           columns.map((column, index) => [column, row[index] ?? null]),
         ),
       );
     return { columns, rows };
   })();

3. Read GEN_VAL_YR as the year-to-date general-import value and CON_VAL_YR as the year-to-date imports-for-consumption value. The CTY_CODE=- parameter requests the aggregate all-country result; omit or replace it only when country-level results are wanted.

Site-Specific Gotchas

• The endpoint is a raw JSON API whose first array is a header row and subsequent arrays are records; map values by those headers rather than relying on positional fields.
• GEN_VAL_YR and CON_VAL_YR are year-to-date measures for the requested time={year}-{month}, not merely that month's values.
• I_COMMODITY={hts-code} is the HTS filter; preserve leading zeroes when an HTS code requires them.
• CTY_CODE=- is the observed aggregate-country selector. For a country-specific query, use the API's country code instead.
• If the API redirects to https://api.census.gov/data/missing_key.html, retry the same endpoint with a caller-supplied &key={api-key}. Never invent a key or perform login/state-changing actions.

Expected Output

Return an object with columns and rows. Each row is an object keyed by the selected API fields, including GEN_VAL_YR, CON_VAL_YR, I_COMMODITY, I_COMMODITY_LDESC, CTY_CODE, CTY_NAME, and LAST_UPDATE.