Shipments

Search and count individual shipment records.

All requests require the X-API-KEY and X-SIGNATURE headers. See Authentication.

POST /api/v1/shipment/search

Search for shipment records matching the specified filter criteria.

Request Body

Field	Type	Required	Constraints	Description
size	integer	Yes	min: 10, max: 10000	Number of shipment records to return
account_name	string	No	—	Account context for this request
importer_countries	array[string]	No	max 10 items	ISO country codes to filter by importer country
exporter_countries	array[string]	No	max 10 items	ISO country codes to filter by exporter country
hs_codes	array[string]	No	max 10 items; numeric only	HS codes to filter by
start_date	string	No	format: `yyyy-MM-dd`	Start of shipment date range
end_date	string	No	format: `yyyy-MM-dd`	End of shipment date range
firm_filter	array[integer]	No	—	Firm type codes to filter by
search_type	string	No	`"importer"` or `"exporter"`	Trade direction to search
product_detail	string	No	min 3 chars	Product description keyword
exporter_firm	string	No	min 3 chars	Exporter firm name keyword
importer_firm	string	No	min 3 chars	Importer firm name keyword
brand_name	string	No	min 3 chars	Brand name keyword
arrival_port	string	No	min 3 chars	Port of arrival keyword
departure_port	string	No	min 3 chars	Port of departure keyword

Response

Field	Type	Description
total	integer	Total number of shipment records matching the query
shipments	array[Shipment]	List of shipment records

Example

JavaScriptcURLJavaPython

import crypto from 'crypto'

const payload = JSON.stringify({
  size: 100,
  search_type: 'importer',
  importer_countries: ['US'],
  hs_codes: ['847130'],
  start_date: '2024-06-01',
  end_date: '2024-06-30'
})

const signature = crypto
  .createHmac('sha256', 'your-api-secret')
  .update(payload)
  .digest('base64')

const res = await fetch('https://apiv2.tradeatlas.com/api/v1/shipment/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your-api-key',
    'X-SIGNATURE': signature
  },
  body: payload
})
const data = await res.json()

bash

PAYLOAD='{"size":100,"search_type":"importer","importer_countries":["US"],"hs_codes":["847130"],"start_date":"2024-06-01","end_date":"2024-06-30"}'

SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "your-api-secret" -binary | base64)

curl -X POST https://apiv2.tradeatlas.com/api/v1/shipment/search \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -H "X-SIGNATURE: $SIGNATURE" \
  -d "$PAYLOAD"

java

String payload = "{\"size\":100,\"search_type\":\"importer\",\"importer_countries\":[\"US\"],\"hs_codes\":[\"847130\"],\"start_date\":\"2024-06-01\",\"end_date\":\"2024-06-30\"}";

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec("your-api-secret".getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String signature = Base64.getEncoder()
    .encodeToString(mac.doFinal(payload.getBytes(StandardCharsets.UTF_8)));

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://apiv2.tradeatlas.com/api/v1/shipment/search"))
    .header("Content-Type", "application/json")
    .header("X-API-KEY", "your-api-key")
    .header("X-SIGNATURE", signature)
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

python

import hmac, hashlib, base64, requests

payload = '{"size":100,"search_type":"importer","importer_countries":["US"],"hs_codes":["847130"],"start_date":"2024-06-01","end_date":"2024-06-30"}'

signature = base64.b64encode(
    hmac.new("your-api-secret".encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://apiv2.tradeatlas.com/api/v1/shipment/search",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "your-api-key",
        "X-SIGNATURE": signature,
    },
    data=payload,
)
data = response.json()

Response

json

{
    "total": 5008,
    "shipments": [
        {
            "importerName": "THE MARKETING GROUP BRANDS INC",
            "importerTaxId": "2024063707114",
            "importerAddress": "3824 Cedar Springs Road, Suite 1030, Dallas Tx 75219 United States",
            "importerCountry": "United States",
            "importerCityState": "Us - Texas",
            "importerEmail": ".",
            "importerFacebook": ".",
            "importerFax": ".",
            "importerInstagram": ".",
            "importerLinkedin": ".",
            "importerTel": ".",
            "importerTwitter": ".",
            "importerWeb": ".",
            "importerCleanUrl": "the-marketing-group-brands-inc",
            "importerUrlCode": "765f4cd6b4f47a12",
            "importerCompanyTypeCode": "0",
            "importerCountryCode": "US",
            "importerTaCode": "us53159774",
            "exporterName": "FOSHAN JUNHUA LIGHTING & ELECTRICAL",
            "exporterTaxId": ".",
            "exporterAddress": "Fuan Industry District,Leliu Town,S, Hunde,,Fo Shan,Cn",
            "exporterCountry": "China",
            "exporterCityState": "China",
            "exporterEmail": ".",
            "exporterFacebook": ".",
            "exporterFax": ".",
            "exporterInstagram": ".",
            "exporterLinkedin": ".",
            "exporterTel": ".",
            "exporterTwitter": ".",
            "exporterWeb": ".",
            "exporterCleanUrl": "foshan-junhua-lighting-electrical",
            "exporterUrlCode": "2aca2efaae0de5fb",
            "exporterCompanyTypeCode": "0",
            "exporterCountryCode": "CN",
            "exporterTaCode": "cn06641255",
            "arrivalDate": "2024-06-30",
            "billOfLadingNo": "MEDUZV609116",
            "conditionNewUsed": "",
            "containerCount": "0.0",
            "countryOfOrigin": "CN",
            "fobValue": "0.00",
            "fobCurrency": "",
            "usdFob": "0.00",
            "cifValue": "0.00",
            "cifCurrency": "",
            "usdCif": "0.00",
            "unitPrice": "0.00",
            "fiCurrency": "",
            "freightAmount": "0.0",
            "grossWeight": "0.00",
            "grossWeightUnit": "",
            "netWeight": "5235.00",
            "netWeightUnit": "Kilogram",
            "quantity": "1700.00",
            "quantityUnit": "Carton",
            "packageAmount": "0.00",
            "packagesUnit": "",
            "hsCode": "8471309000",
            "hsCodeDescription": "",
            "hsCodeKeyword": "847130",
            "insuranceAmount": "0.0",
            "manufacturingCompany": "",
            "brandName": "",
            "incoterms": "",
            "paymentType": "",
            "regime": "Import",
            "transportType": "Vessel, containerized",
            "notifyParty": "SPECIALTY CARGO TRANSPORT LLC",
            "notifyAddress": "2134 VALLEY SAND STREET _ LAS VEGAS NV 89135 UNITED STATES _",
            "portOfArrival": "5501, DALLAS-FORT WORTH, TX",
            "portOfDeparture": "57078, CN, YANTIAN",
            "itemNo": "0.0",
            "declarationNumber": "000001",
            "importerDataType": "",
            "exporterDataType": "",
            "dataType": "",
            "transportCompany": "MEDU",
            "vesselName": "MSC ROSA M",
            "productDetails": "KAMBIRA 2PK SOLAR LAMP POST AND PLANTER-BK MA, DISON SOLAR LAMP POST AND PLANTER-KD VERSION, PO# 240064 SHIPPER DECLARED THAT THIS SHIPMEN, T CONTAINS NO SOLID WOOD PACKING MATERIALS | J&J GLOBAL,LLC P.O. NUMBER: DIMENSIONS: NW: G, W: MADE IN CHINA CTN NO., SAME",
            "statisticalValueUsd": "0.0",
            "totalTeus": "2.0",
            "updatedAt": "1745934576.540106311",
            "createdAt": "1745934576.540106311",
            "addedGroup": "yeni_veri_P7_US_2024_FULL_00_06-2025-04-24.zip",
            "hashId": "1WBX10TiVGs+gdLTSpXNvQ==",
            "month": "6",
            "year": "2024"
        }
    ]
}

POST /api/v1/shipment/count

Count shipment records for a specific firm. The firm field is required.

Request Body

Field	Type	Required	Constraints	Description
firm	string	Yes	non-empty	importerUrlCode/exporterUrlCode to count shipments for
account_name	string	No	—	Account context for this request
importer_countries	array[string]	No	max 10 items	ISO country codes to filter by importer country
exporter_countries	array[string]	No	max 10 items	ISO country codes to filter by exporter country
hs_codes	array[string]	No	max 10 items; numeric only	HS codes to filter by
start_date	string	No	format: `yyyy-MM-dd`	Start of shipment date range
end_date	string	No	format: `yyyy-MM-dd`	End of shipment date range
firm_filter	array[integer]	No	—	Firm type codes to filter by
search_type	string	No	`"importer"` or `"exporter"`	Trade direction to search
product_detail	string	No	min 3 chars	Product description keyword
exporter_firm	string	No	min 3 chars	Exporter firm name keyword
importer_firm	string	No	min 3 chars	Importer firm name keyword
brand_name	string	No	min 3 chars	Brand name keyword
arrival_port	string	No	min 3 chars	Port of arrival keyword
departure_port	string	No	min 3 chars	Port of departure keyword

Response

Field	Type	Description
shipment_count	integer	Total number of shipments for the specified firm

Example

JavaScriptcURLJavaPython

import crypto from 'crypto'

const payload = JSON.stringify({
  firm: 'Tech Imports LLC',
  search_type: 'importer',
  importer_countries: ['US'],
  start_date: '2024-01-01',
  end_date: '2024-12-31'
})

const signature = crypto
  .createHmac('sha256', 'your-api-secret')
  .update(payload)
  .digest('base64')

const res = await fetch('https://apiv2.tradeatlas.com/api/v1/shipment/count', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your-api-key',
    'X-SIGNATURE': signature
  },
  body: payload
})
const data = await res.json()

bash

PAYLOAD='{"firm":"Tech Imports LLC","search_type":"importer","importer_countries":["US"],"start_date":"2024-01-01","end_date":"2024-12-31"}'

SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "your-api-secret" -binary | base64)

curl -X POST https://apiv2.tradeatlas.com/api/v1/shipment/count \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -H "X-SIGNATURE: $SIGNATURE" \
  -d "$PAYLOAD"

java

String payload = "{\"firm\":\"Tech Imports LLC\",\"search_type\":\"importer\",\"importer_countries\":[\"US\"],\"start_date\":\"2024-01-01\",\"end_date\":\"2024-12-31\"}";

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec("your-api-secret".getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String signature = Base64.getEncoder()
    .encodeToString(mac.doFinal(payload.getBytes(StandardCharsets.UTF_8)));

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://apiv2.tradeatlas.com/api/v1/shipment/count"))
    .header("Content-Type", "application/json")
    .header("X-API-KEY", "your-api-key")
    .header("X-SIGNATURE", signature)
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

python

import hmac, hashlib, base64, requests

payload = '{"firm":"Tech Imports LLC","search_type":"importer","importer_countries":["US"],"start_date":"2024-01-01","end_date":"2024-12-31"}'

signature = base64.b64encode(
    hmac.new("your-api-secret".encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://apiv2.tradeatlas.com/api/v1/shipment/count",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "your-api-key",
        "X-SIGNATURE": signature,
    },
    data=payload,
)
data = response.json()

Response

json

{
  "shipment_count": 142
}

Shipments ​

POST /api/v1/shipment/search ​

POST /api/v1/shipment/count ​

Shipments

POST /api/v1/shipment/search

POST /api/v1/shipment/count