Usage Statistics

Endpoint for querying your account's API usage and limits.

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

---

GET /api/v1/statistics/usage

Returns the usage and limit summary for the authenticated caller's own accounts. Takes no request body or parameters.

SIGNATURE (GET)

This is a GET request with no body. The X-SIGNATURE is computed over an empty string "". See Authentication.

Response

The response is a nested object of the form { account name → { metric → summary } }. Each metric contains the following fields:

Field	Type	Description
current	integer	Amount consumed so far for this metric
limit	integer	Allowed upper limit. -1 means unlimited
notes	string	Optional. "unlimited" when the limit is unlimited; the list of searched HS codes for searchedHsCodes

Metrics

Metric	Meaning
firms/search	Firm search (download) usage
firms/count	Firm count usage
shipments/search	Shipment search (download) usage
shipments/count	Shipment count usage
searchedHsCodes	Number of distinct HS codes searched
dailyRequest	Daily request count
minutelyRequest	Per-minute request count

Example

JavaScript

import crypto from 'crypto'

const payload = '' // GET request has no body

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

const res = await fetch('https://apiv2.tradeatlas.com/api/v1/statistics/usage', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'your-api-key',
    'X-SIGNATURE': signature
  }
})
const data = await res.json()

cURL

SIGNATURE=$(printf '' | openssl dgst -sha256 -hmac "your-api-secret" -binary | base64)

curl -X GET https://apiv2.tradeatlas.com/api/v1/statistics/usage \
  -H "X-API-KEY: your-api-key" \
  -H "X-SIGNATURE: $SIGNATURE"

Java

String payload = ""; // GET request has no body

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/statistics/usage"))
    .header("X-API-KEY", "your-api-key")
    .header("X-SIGNATURE", signature)
    .GET()
    .build();

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

Python

import hmac, hashlib, base64, requests

payload = ""  # GET request has no body

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

response = requests.get(
    "https://apiv2.tradeatlas.com/api/v1/statistics/usage",
    headers={
        "X-API-KEY": "your-api-key",
        "X-SIGNATURE": signature,
    },
)
data = response.json()

Response

{
  "My Account": {
    "firms/search":     { "current": 1240, "limit": 5000 },
    "firms/count":      { "current": 87,   "limit": 1000 },
    "shipments/search": { "current": 1240, "limit": 5000 },
    "shipments/count":  { "current": 87,   "limit": 1000 },
    "searchedHsCodes":  { "current": 3,    "limit": 50, "notes": "[847130, 850760, 852990]" },
    "dailyRequest":     { "current": 320,  "limit": 10000 },
    "minutelyRequest":  { "current": 5,    "limit": 120 }
  }
}

An unlimited limit is returned as -1 with "notes": "unlimited" on that metric.