Docs → API reference

Robotics Trade (industrial-robot imports, value + robot counts) API v1

Generated from core.contract.describe_robotics_trade_v1() and checked fixture-backed examples. Do not hand-edit the example JSON files.

Capability

• Capability: robotics.trade
• Primitive: query_robotics_trade_v1
• Status: available
• Current source: trade.census.intltrade_robotics_hs
• Source publisher: U.S. Census Bureau
• Snapshot behavior: as_of = latest resolves to an exact snapshot date in every response.

What It Can Answer

• Monthly U.S. imports of industrial robots in customs value (USD) AND unit counts (number of robots) — cited to the source row.
• Robot imports by country of origin (e.g. Japan, China, South Korea, Germany, Mexico) — supply concentration, by dollars or by units.
• The two robot categories separately — multipurpose robots (HS-10 8479500000) vs lifting/handling robots (8428700000, from 2022-01 only).
• General imports vs imports-for-consumption at the same grain, value and units.
• Row-level detail records when include_records is true.
• Raw Census response-row evidence for any returned row-level citation.

Represented Facts

• Census International Trade reports the monthly customs value (USD) AND unit count (number of robots) of U.S. imports of industrial robots — HS-10 8479500000 'INDUSTRIAL ROBOTS, NESOI' (multipurpose) and 8428700000 'INDUSTRIAL ROBOTS FOR LIFTING, HANDLING, LOADING OR UNLOADING' (created by HS 2022; no data before 2022-01) — by country of origin, as general imports and imports-for-consumption, served verbatim and cited
• Census reports these imports across overlapping country GROUPINGS (ASIA, APEC, EU, OECD, ASEAN, the continents) and an all-countries TOTAL; the groupings overlap each other and the countries, so they are never summed — the served TOTAL is the only national figure

Data Point Contract

• Data point: robotics.trade
• Product spec: blocks/robotics_trade/card.md
• Grain: commodity_country_monthly
• Source basis: trade.census.intltrade_robotics_hs
• Represented fact: Census International Trade reports the monthly customs value (USD) AND unit count (number of robots) of U.S. IMPORTS of industrial robots under the nomenclature's only two robot-specific codes — HS-10 8479500000 "INDUSTRIAL ROBOTS, NESOI" (multipurpose: welding/assembly arms, AMRs) and 8428700000 "INDUSTRIAL ROBOTS FOR LIFTING, HANDLING, LOADING OR UNLOADING, NESOI" (created by HS 2022, carved from ex-8428.90; NO data exists under it before 2022-01 — a structural absence, never a zero) — by country of origin and as Census's own published country GROUPINGS and TOTAL. Served as four series exactly as Census publishes: general imports and imports-for-consumption, each in value and units. Each row is served verbatim + cited; the country groupings overlap and are never summed; the two commodity codes are disjoint but a cross-code series changes composition at 2022-01.

Does not answer:

• the installed base or operational stock of robots in US factories — this is the monthly import FLOW (the stock series is IFR World Robotics, proprietary; the official adoption series is the Census Industrial Robotic Equipment experimental product — the vertical's named block 2)
• robots by maker, model, or type beyond the two-code split — no vendor series, no humanoid breakout (customs-classified — AMRs fall under 8479.50 per CBP N335129; a humanoid DEMONSTRATION unit can classify under 9023 per CBP H050116, outside these codes)
• domestic robot production — imports only; there is no robotics NAICS industry (robot manufacturing hides inside NAICS 333998, a grab-bag we refuse to mislabel)
• summing across country rows — Census's groupings (ASIA, APEC, EU, OECD, ASEAN, the continents) OVERLAP each other and the individual countries; the served "TOTAL FOR ALL COUNTRIES" (country_level=total) is the only valid total, never a sum the agent computes
• a pre-2022 reading of 8428700000 — the code was created by HS 2022; earlier lifting/handling robots sat inside ex-8428.90 (not served here); a cross-code time series changes composition at 2022-01
• landed / CIF / duty-paid cost — general imports value is customs value; CIF, charges, and calculated duty are separate Census fields not served here
• which U.S. factory, state, county, or operator receives the robots — country is the country of ORIGIN (Census attribution), not a U.S. destination; this series carries no U.S. geographic anchor
• exports (this block serves IMPORTS only) or trade in non-robot goods
• finality (recent months are preliminary and revised in later Census releases)

REST Surface

• GET /v1/health
• GET /v1/capabilities
• GET /v1/robotics/trade/schema
• POST /v1/robotics/trade/query
• POST /v1/evidence/source-row

MCP Surface

• list_capabilities_v1
• describe_robotics_trade_v1
• query_robotics_trade_v1
• get_source_evidence_v1

Local MCP Setup

Some MCP clients launch servers from the user's home directory or ignore a configured cwd. Use uv run --directory so the server always starts from the repository project.

{
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "/absolute/path/to/OSINT",
    "python",
    "-m",
    "core.mcp_server"
  ]
}

Leave EXASCALE_PARQUET_BASE / EXASCALE_RAW_BASE unset: the one server hosts every data point's tools, and with no override it resolves each block's promoted snapshots and raw archive from the repository layout. Setting either env var points ALL tools at one directory — a per-block path breaks every other block's tools. They exist only for single-source sandboxes and tests.

Request Schema

Filters:

• as_of
• commodity
• country
• cty_code
• country_level
• data_month
• data_month_from
• data_month_to
• year

Input field semantics:

Group by:

• commodity
• country
• cty_code
• country_level
• data_month
• year

Date range parameters:

• data_month_from
• data_month_to

Controls:

• include_records
• include_evidence
• limit
• order_by
• top_n
• order
• rollup_other

Ranking (how order_by / top_n / order join — order_by ranks groups by a metric, never a group_by dimension; top_n needs both a group_by and an order_by):

{
  "no_ranking": "Omit order_by and top_n to return all groups in group-key order.",
  "order": {
    "default": "desc",
    "valid_values": [
      "desc",
      "asc"
    ]
  },
  "order_by": {
    "accepts": "one of output.metrics",
    "note": "Ranks the groups by a metric (a measure). Not a group_by dimension \u2014 rows already come back grouped by each group_by field.",
    "requires": [
      "group_by"
    ],
    "valid_values": [
      "general_value_usd",
      "consumption_value_usd",
      "general_quantity_units",
      "consumption_quantity_units",
      "source_record_count"
    ]
  },
  "top_n": {
    "note": "Keeps the top N groups by order_by; the rest fold into one (other) remainder (additive metrics sum into it, non-additive ones are nulled) so the result still reconciles to summary.totals.",
    "requires": [
      "group_by",
      "order_by"
    ],
    "type": "positive integer"
  }
}

Output Schema

Aggregate metrics:

• general_value_usd
• consumption_value_usd
• general_quantity_units
• consumption_quantity_units
• source_record_count

Metric groups:

{
  "consumption_quantity_units": [
    "consumption_quantity_units"
  ],
  "consumption_value_usd": [
    "consumption_value_usd"
  ],
  "general_quantity_units": [
    "general_quantity_units"
  ],
  "general_value_usd": [
    "general_value_usd"
  ],
  "records": [
    "source_record_count"
  ]
}

Response summary fields:

• group_count
• totals

Accepted fact policy:

• Query responses contain accepted, gate-passed facts only.
• Gate, monitor, and audit quality signals are internal controls, not agent-facing answer caveats.
• If a source snapshot is not fit to serve, the source must fail closed before it reaches this API.

Metric metadata:

Rollup rules:

• summary.totals.<metric> is the authoritative total for the full matched query.
• Grouped row metrics may be summed only when additive_across_groups is true.
• Do not sum grouped values for these non-additive metrics: general_value_usd, consumption_value_usd, general_quantity_units, consumption_quantity_units.

Detail record fields returned when include_records is true:

• source_id
• sheet_name
• source_record_key
• report_period
• commodity
• commodity_desc
• cty_code
• country
• country_level
• data_month
• year
• general_value_usd
• consumption_value_usd
• general_quantity_units
• consumption_quantity_units
• quantity_unit
• source_row_number
• as_of
• raw_file_sha256
• citation

Row-level citation fields:

• source_id
• source_url
• source_file
• sheet
• source_row
• raw_file_sha256
• as_of

Aggregate citation fields:

• source_id
• publisher
• source_url
• source_file
• raw_file_sha256
• as_of
• source_rows_count
• source_rows_sample
• verify
• lineage_filter

Codebooks

The complete machine-readable codebooks are included in capability-schema.json.

Checked Examples

The checked schema output is capability-schema.json.

Agent Workflow

1. Call list_capabilities_v1 and select robotics.trade.
2. Call describe_robotics_trade_v1 to inspect valid filters, groupings, metrics, and citation fields.
3. Call query_robotics_trade_v1 with bounded JSON params.
4. If the answer needs proof, pass a returned row-level citation object to get_source_evidence_v1.
5. Answer with the resolved as_of and relevant citations. Present returned metrics as authoritative for their declared source, snapshot, grain, and aggregation.