Firms

Search and count trade firms (importers or exporters).

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

POST /api/v1/firms/search

Search for firms matching the specified filter criteria. Returns a paginated list of firm records.

Request Body

Field	Type	Required	Constraints	Description
page	integer	Yes	min: 1	Page number to retrieve
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. Defaults to `["ALL"]` if omitted
exporter_countries	array[string]	No	max 10 items	ISO country codes to filter by exporter country; requires at least one other parameter
hs_codes	array[string]	No	max 10 items; numeric characters 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

At least one filter parameter is required. exporter_countries requires at least one additional parameter. NOT-operator parameters cannot be used without a positive parameter.

Response

Field	Type	Description
total_shipment	integer	Total shipment records matching the query
total_pages	integer	Total number of pages available
page	integer	Current page number
firms_count	integer	Number of firms returned in this page
firms	array[Firm]	List of firm records

Example

JavaScriptcURLJavaPython

import crypto from 'crypto'

const payload = JSON.stringify({
  page: 1,
  search_type: 'importer',
  importer_countries: ['US', 'DE'],
  hs_codes: ['847130'],
  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/firms/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='{"page":1,"search_type":"importer","importer_countries":["US","DE"],"hs_codes":["847130"],"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/firms/search \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -H "X-SIGNATURE: $SIGNATURE" \
  -d "$PAYLOAD"

java

String payload = "{\"page\":1,\"search_type\":\"importer\",\"importer_countries\":[\"US\",\"DE\"],\"hs_codes\":[\"847130\"],\"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/firms/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 = '{"page":1,"search_type":"importer","importer_countries":["US","DE"],"hs_codes":["847130"],"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/firms/search",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "your-api-key",
        "X-SIGNATURE": signature,
    },
    data=payload,
)
data = response.json()

Response

json

{
  "total_shipment": 15420,
  "total_pages": 31,
  "page": 1,
  "firms_count": 500,
  "firms": [
    {
      "country": "United States",
      "country_code": "US",
      "name": "Tech Imports LLC",
      "address": "123 Commerce St, New York, NY 10001",
      "city_state": "New York, NY",
      "tel": "+1 212 555 0100",
      "e_mail": "[email protected]",
      "web": "www.techimports.example.com",
      "firm_type": 1,
      "shipment_count": 42
    }
  ]
}

POST /api/v1/firms/count

Count firms matching the specified filter criteria.

Request Body

Accepts the same filter fields as /api/v1/firms/search, without the page field.

Field	Type	Required	Constraints	Description
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
firm_count	integer	Total number of firms matching the query

Example

JavaScriptcURLJavaPython

import crypto from 'crypto'

const payload = JSON.stringify({
  search_type: 'exporter',
  exporter_countries: ['CN', 'IN'],
  hs_codes: ['847130'],
  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/firms/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='{"search_type":"exporter","exporter_countries":["CN","IN"],"hs_codes":["847130"],"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/firms/count \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -H "X-SIGNATURE: $SIGNATURE" \
  -d "$PAYLOAD"

java

String payload = "{\"search_type\":\"exporter\",\"exporter_countries\":[\"CN\",\"IN\"],\"hs_codes\":[\"847130\"],\"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/firms/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 = '{"search_type":"exporter","exporter_countries":["CN","IN"],"hs_codes":["847130"],"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/firms/count",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "your-api-key",
        "X-SIGNATURE": signature,
    },
    data=payload,
)
data = response.json()

Response

json

{
  "firm_count": 1284
}

Firms ​

POST /api/v1/firms/search ​

POST /api/v1/firms/count ​

Firms

POST /api/v1/firms/search

POST /api/v1/firms/count