# USITC DataWeb MCP

> USITC DataWeb connects your AI client to official U.S. international trade data. Query import/export statistics, trade balances, and commodity values using recognized classification codes like HS, SITC, or NAICS. It lets you pull complex economic records—from country-level totals down to specific product categories—without needing manual database joins or CSV downloads.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** international-trade, import-export, tariff-data, economic-statistics, trade-balance, commodity-data

## Description

Look, you gotta connect your agent to the USITC DataWeb server if you wanna pull official U.S. international trade numbers. This thing lets you run detailed queries on global imports, exports, and total trade balances—no messing around with manual data joins or downloading massive CSV files. It's all about querying structured government records directly through simple instructions. You don't gotta know the underlying API structure; your AI client handles all that heavy lifting.

When you start out, the first thing you need to do is figure out what datasets are even available. You use `list_metadata_tables` to get a list of every core dataset—every table in the USITC repository. This tells you if they got 'imports' or maybe 'exports' listed right there so you know where to start looking.

Once you pinpoint the right dataset, you gotta inspect it. You call `list_metadata_fields` to check which specific columns and data points are available within that chosen table. It shows you exactly what fields exist—which is crucial because different tables store different kinds of numbers, like raw commodity volumes versus dollar values.

Before you run the main query, you need to validate your inputs. You use `list_metadata_values` to confirm valid entries for any filter field you plan on using. Need to filter by country? This tool shows you the official country codes so you don't accidentally send bad data. It works the same way for specific commodity levels or other categorical filters, keeping sure your query is airtight.

Finally, when you're ready, you run `query_trade_data`. You pass along all those validated parameters—the HS code, the country filter, the time period—and it pulls the detailed US trade statistics. This tool runs the main query to retrieve specific trade volumes and values using complex filters like classification codes (HS/SITC/NAICS), a specified country, and a date range.

It's designed for anyone who needs reliable, official numbers without building out complicated SQL queries or wrestling with messy data formats. You can get everything from broad country-level totals down to specific product categories using the classification codes. The system supports large filter sets via POST requests, meaning you can load up your query parameters and it handles them. It's straightforward: find the table, check the columns, validate your inputs, then run the main query. That’s how you pull accurate trade data.

## Tools

### list_metadata_fields
Shows a list of all columns available in a specific data table so you know what fields to query.

### list_metadata_tables
Retrieves the names of every core dataset (table) hosted on the USITC DataWeb server.

### list_metadata_values
Lists all valid entries for a filter field, like country codes or specific commodity levels, ensuring your data is accurate.

### query_trade_data
Runs the main query to pull detailed US trade statistics based on filters like HS code, country, and time period.

## Prompt Examples

**Prompt:** 
```
List all available metadata tables from USITC DataWeb.
```

**Response:** 
```
I've retrieved the available tables. You can query data from tables such as 'imports', 'exports', and 'balance'. Which one would you like to explore?
```

**Prompt:** 
```
Show me the fields available for the 'imports' table.
```

**Response:** 
```
For the 'imports' table, you can use fields such as 'commodity', 'country', 'year', 'month', and 'customs_value'. Would you like to see valid values for any of these?
```

**Prompt:** 
```
Query trade data for HS code '01' from Canada (1220) for the year 2022.
```

**Response:** 
```
I've processed the query for HS code '01' (Live Animals) from Canada in 2022. The total import value was $X million. Would you like a breakdown by month?
```

## Capabilities

### List available data tables
Find out what core datasets (like 'imports' or 'exports') exist in the USITC repository using `list_metadata_tables`.

### Inspect table fields
Check which specific columns and data points are available within a chosen dataset by calling `list_metadata_fields`.

### Validate input values
Confirm valid entries for categorical filters, such as official country codes or commodity levels, using `list_metadata_values`.

### Query trade statistics
Run the main query to retrieve specific trade volumes and values using `query_trade_data`, filtering by classification code (HS/SITC/NAICS), country, and time period.

## Use Cases

### Comparing commodity shifts over a decade
A researcher needs to see how the trade volume for electronics changed from 2010 to 2020. They ask their agent, which first uses `list_metadata_tables` to find the 'exports' table. Then it uses `query_trade_data`, filtering by the commodity code and specifying a decade-long date range. The result is a clean, time-series data set.

### Verifying country codes before querying
A supply chain analyst wants to check trade between Vietnam and India. They first use `list_metadata_values` on the 'country' field to confirm both nations have active, correct codes for that specific data table. Once validated, they run `query_trade_data` knowing their inputs are official.

### Auditing a tariff change
A policy researcher needs data on textiles using the HS code system. They use the metadata tools to confirm the correct table and fields, then run `query_trade_data` for a specific period (e.g., before/after a policy date). This process provides audited numbers directly from the government source.

### Finding out what data is available
A new analyst lands on the server and doesn't know where to start. They simply call `list_metadata_tables`, which returns 'imports', 'exports', and 'balance'. This immediately narrows their focus and tells them exactly which datasets they need for their task.

## Benefits

- You get immediate access to full trade volumes and values for specific sectors. Instead of downloading massive CSV files, your agent uses `query_trade_data` to deliver the precise data points you need right in your workspace.
- Stop guessing which columns exist. Use `list_metadata_fields` first. It shows exactly what data a table contains—commodity, country, year—so you build your queries with confidence.
- Never worry about invalid filters again. Before querying, use `list_metadata_values` to get the official list of valid country codes or commodity classifications for that specific dataset.
- Analyze trends over time easily. Run historical comparisons by specifying a date range in `query_trade_data`. You can compare trade data from 2010 vs. 2022, instantly.
- Work with multiple classification standards simultaneously. The server supports querying using Harmonized Tariff Schedule (HS), SITC, or NAICS codes, making your analysis comprehensive.

## How It Works

The bottom line is: You ask your agent a question about global trade, and it uses these tools to pull official data without you writing any API calls yourself.

1. Subscribe to the server and provide your USITC DataWeb API Key.
2. Use `list_metadata_tables` or `list_metadata_fields` to scope out exactly what data is available for your query.
3. Invoke `query_trade_data`, passing the specific filters (e.g., commodity code, country) and time frame you need.

## Frequently Asked Questions

**How do I find the correct country code for a trade query?**
You can use the `list_metadata_values` tool. Provide the table ID (e.g., 'imports') and the field ID for countries to see a full list of valid USITC country codes.

**What classification systems are supported for commodity queries?**
The server supports 'hs' (Harmonized System), 'sitc' (Standard International Trade Classification), and 'naics' (North American Industry Classification System) via the `query_trade_data` tool.

**Can I see what data tables are available before querying?**
Yes, use the `list_metadata_tables` tool to retrieve a list of all available data tables and their identifiers from the USITC DataWeb API.

**What credentials are required to run `query_trade_data` on USITC DataWeb?**
You must provide a valid API Key. The server requires you to supply your specific USITC DataWeb API Key during the setup process to authorize all data retrievals.

**Before running `query_trade_data`, what is the best way to validate country or commodity codes?**
Use the `list_metadata_values` tool. This function provides a list of valid values for any given field in a table, helping you avoid query failures caused by bad inputs.

**Which tool should I use to view the exact data points available for an export record?**
Use `list_metadata_fields`. This function returns all usable field names—like 'commodity' or 'customs_value'—for a specific table you want to analyze. It shows what metrics are actually trackable.

**How does the USITC DataWeb handle very large or complex filter sets when I run `query_trade_data`?**
The tool uses a POST method, which is designed to support large filter sets. This mechanism lets you send and process complicated queries with many criteria without hitting limitations.

**Does `query_trade_data` support granular time-series analysis, like monthly reports?**
Yes, the tool handles both annual and monthly granularity. You simply need to specify the desired time period (year/month) in your query parameters when you call the function.