Tradaro

Developer documentation · v1.0.0

Published trade data, through one API

Query official records with their source, publication and confidence. Build integrations around the same releases used by Tradaro.

https://api.tradaro.com/v1

Get started

An organisation owner creates a key in API key settings. Copy it when it is shown, then store it in your server’s secret configuration as TRADARO_API_KEY. Send it in the Authorization header on every request.

curl --fail-with-body --include 'https://api.tradaro.com/v1/reporters' \
  --header "Authorization: Bearer $TRADARO_API_KEY"

read permits data reads. bulk permits export creation, polling and downloading; a bulk-only key can use exports. Effective permissions also depend on your organisation’s current access. Revocation takes effect on the next request.

Call from your server: browser CORS access is not advertised. Keep keys out of URLs and browser code. Examples below are synthetic fixtures; operator IDs, months and amounts are not promises about live data.

Source provenance

Read meta.release and X-Tradaro-Release to identify the published snapshot. References also carry their revision when applicable. Row-level source, tier, method, confidence and revision describe the record; aggregates state their derivation explicitly.

Preserve codes as strings, including leading zeroes and residual codes. Null means unavailable or withheld, never zero. Suppressed trade measures stay null. HMRC operator links identify appearances and do not publish shipment values; their value stays null. These endpoints do not return estimates.

Create an asynchronous export

  1. POST a supported list endpoint, its string filters and csv or parquet format. Omit limit and cursor from params.
  2. A 202 response gives a Location to poll. Wait for Retry-After, then GET that status URL until completed, failed or expired.
  3. When completed, GET download_url with the same key. This returns file bytes. Verify X-Tradaro-Content-SHA256 against the downloaded file.
curl --fail-with-body --include --request POST 'https://api.tradaro.com/v1/exports' \
  --header "Authorization: Bearer $TRADARO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"endpoint":"/flows","params":{"commodity":"02071410"},"format":"csv","row_limit":2}'

Only the creating key can poll or download, including within the same organisation. CSV includes a UTF-8 BOM and header; Parquet retains nullable native types. Generation stays on one publication and reference snapshot. A completed file remains that snapshot until expiry, while key and entitlement checks still apply.

The creation operation below documents row, byte, concurrency and expiry limits, fixed column order, CSV formula handling and terminal error codes. Status URLs already start with /v1: resolve them against https://api.tradaro.com, without adding /v1 again.

Handle errors

Errors use a JSON envelope with error.code, error.message and error.request_id. Retain the request ID when contacting support. A rate or quota response returns 429; wait for Retry-After. Fix credentials, permissions or filters before retrying other rejected requests.

Send only documented parameters and no body with GET requests. JSON responses are not cacheable. Export downloads return bytes on success and the JSON error envelope on failure.

Error

  • Unknown properties are refused.

Operation reference

Paths are relative to the base URL. Open an operation for its complete parameters, schemas, headers, examples and export columns.

Catalogue

Loaded markets, publications and derived release differences.

GET/reportersread scopeList available reporters

Returns only loaded markets visible to this key. No query parameters or body. Empty data is valid. Includes the actual source licence and attribution; adapters for unloaded markets are not advertised.

curl --fail-with-body --include 'https://api.tradaro.com/v1/reporters' \
  --header "Authorization: Bearer $TRADARO_API_KEY"

Parameters

No path or query parameters.

Responses

200Successful response.

application/json

ReportersResponse

  • Unknown properties are refused.
Example: Synthetic published fixture
{
  "data": [
    {
      "reporter": "GB",
      "name": "United Kingdom",
      "source": "hmrc_uktradeinfo",
      "latest_period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "loaded_at": "2026-09-11T00:00:00.000000Z",
      "licence": {
        "name": "Open Government Licence v3.0",
        "url": "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
        "attribution": "Contains public sector information licensed under the Open Government Licence v3.0. HMRC does not endorse Tradaro."
      }
    }
  ],
  "meta": {
    "count": 1
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

CSV / Parquet export columns, in order

CSV represents null as an empty field. Parquet uses the nullable types below. Source codes remain strings.

  1. reporterNullable(String)
  2. nameNullable(String)
  3. sourceNullable(String)
  4. latest_periodNullable(String)
  5. generationNullable(String)
  6. loaded_atNullable(String)
  7. licenceNullable(String)
  8. release_sourceNullable(String)
  9. release_periodNullable(String)
  10. release_generationNullable(String)
  11. reference_revisionNullable(String)
GET/releasesread scopeList published releases

Newest month first. Pagination is bound to the reporter filter. Each row carries its generation, publication times and counts for the five difference kinds; meta has no selected release object. No request body.

curl --fail-with-body --include 'https://api.tradaro.com/v1/releases' \
  --header "Authorization: Bearer $TRADARO_API_KEY"

Parameters

ParameterLocationDescription and constraints
reporterOptionalquery

Optional reporter filter. Without it, returns loaded markets within your entitlement. An entitled but unloaded market gives an empty list.

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"

Example: "GB"

limitOptionalquery

Maximum rows per page, 1–500 (default 100). Send one canonical decimal value, without a leading zero; array values are refused.

integer

  • Minimum: 1
  • Maximum: 500
  • Default: 100

Example: 100

cursorOptionalquery

Opaque token from meta.next_cursor, bound to the reporter filter. Releases are ordered by descending month.

string

  • Maximum characters: 256
  • Pattern: "^[A-Za-z0-9_-]+$"

Responses

200Successful response.

application/json

ReleasesResponse

  • Unknown properties are refused.
Example: Synthetic published fixture
{
  "data": [
    {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "previous_period": "2026-05",
      "history_start": "2026-01",
      "summary": {
        "new_operator": 0,
        "operator_returned": 0,
        "new_operator_commodity": 0,
        "new_partner_for_commodity": 0,
        "commodity_value_change": 0
      },
      "loaded_at": "2026-09-11T00:00:00.000000Z",
      "diff_computed_at": "2026-09-11T00:00:00.000000Z",
      "observed_at": "2026-09-11T00:00:00.000000Z"
    }
  ],
  "meta": {
    "count": 1,
    "limit": 100,
    "next_cursor": null
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

CSV / Parquet export columns, in order

CSV represents null as an empty field. Parquet uses the nullable types below. Source codes remain strings.

  1. sourceNullable(String)
  2. reporterNullable(String)
  3. periodNullable(String)
  4. previous_periodNullable(String)
  5. history_startNullable(String)
  6. generationNullable(String)
  7. summaryNullable(String)
  8. loaded_atNullable(String)
  9. diff_computed_atNullable(String)
  10. observed_atNullable(String)
  11. release_sourceNullable(String)
  12. release_periodNullable(String)
  13. release_generationNullable(String)
  14. reference_revisionNullable(String)
GET/diffsread scopeList release differences

Requires both read scope and the organisation’s differences/alerts entitlement. Reads one immutable release generation, ordered by kind and subject. The five categories compare declared monthly CN8 data; decimal value changes remain strings. meta.total is the selected category count before pagination. No request body.

curl --fail-with-body --include 'https://api.tradaro.com/v1/diffs' \
  --header "Authorization: Bearer $TRADARO_API_KEY"

Parameters

ParameterLocationDescription and constraints
reporterOptionalquery

Reporter market; defaults to GB. Entitlements are enforced before warehouse reads.

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
  • Default: "GB"

Example: "GB"

periodOptionalquery

Published month; defaults to the latest release. An absent release is not inferred from another month.

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"

Example: "2026-06"

kindOptionalquery

Restrict to one difference category; omitted returns all five categories.

DiffKind

  • Allowed: "new_operator", "operator_returned", "new_operator_commodity", "new_partner_for_commodity", "commodity_value_change"

Example: "new_operator"

limitOptionalquery

Maximum rows per page, 1–500 (default 100). Send one canonical decimal value, without a leading zero; array values are refused.

integer

  • Minimum: 1
  • Maximum: 500
  • Default: 100

Example: 100

cursorOptionalquery

Opaque token from meta.next_cursor. Keep all filters unchanged; null means the end. Do not decode or construct tokens.

Cursor

Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change.

  • Maximum characters: 4096
  • Pattern: "^[A-Za-z0-9_-]+$"

Responses

200Successful response.

application/json

DiffsResponse

  • Unknown properties are refused.
Example: Synthetic published fixture
{
  "data": [
    {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "kind": "new_operator",
      "subject": "000123",
      "detail": {
        "operator_ref": "000123",
        "operator_name": "Example Foods Ltd"
      },
      "tier": null,
      "method": "derived",
      "confidence": null,
      "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "basis": "monthly-declared-cn8-v1"
    }
  ],
  "meta": {
    "count": 1,
    "limit": 100,
    "next_cursor": null,
    "release": {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "total": 1
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

404Resource or requested published month not found. Foreign export keys also receive 404.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

409Publication changed, organisation already has five active exports, or export is not downloadable. Restart data pagination after publication_changed.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "publication_changed",
    "message": "The publication changed during this request. Restart pagination.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

CSV / Parquet export columns, in order

CSV represents null as an empty field. Parquet uses the nullable types below. Source codes remain strings.

  1. sourceNullable(String)
  2. reporterNullable(String)
  3. periodNullable(String)
  4. generationNullable(String)
  5. kindNullable(String)
  6. subjectNullable(String)
  7. detailNullable(String)
  8. tierNullable(String)
  9. methodNullable(String)
  10. confidenceNullable(String)
  11. revisionNullable(String)
  12. basisNullable(String)
  13. release_sourceNullable(String)
  14. release_periodNullable(String)
  15. release_generationNullable(String)
  16. reference_revisionNullable(String)

Operators

Declared trader-directory identities and appearances.

GET/operatorsread scopeSearch declared operators

Case-insensitive name search within published trader-directory appearances. Totals describe distinct published links and months, not company trade values. Up to six source commodity codes accompany each result. No request body.

curl --fail-with-body --include 'https://api.tradaro.com/v1/operators?q=foods' \
  --header "Authorization: Bearer $TRADARO_API_KEY"

Parameters

ParameterLocationDescription and constraints
qRequiredquery

Case-insensitive substring of the operator name. Trimmed length must be 2–80 Unicode characters; control characters are refused. Prefix matches rank first, then months descending, name and source reference.

string

  • Minimum characters: 2
  • Maximum characters: 80

Example: "foods"

reporterOptionalquery

Reporter market; defaults to GB. Entitlements are enforced before warehouse reads.

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
  • Default: "GB"

Example: "GB"

limitOptionalquery

Maximum rows per page, 1–500 (default 100). Send one canonical decimal value, without a leading zero; array values are refused.

integer

  • Minimum: 1
  • Maximum: 500
  • Default: 100

Example: 100

cursorOptionalquery

Opaque token from meta.next_cursor. Keep all filters unchanged; null means the end. Do not decode or construct tokens.

Cursor

Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change.

  • Maximum characters: 4096
  • Pattern: "^[A-Za-z0-9_-]+$"

Responses

200Successful response.

application/json

OperatorsResponse

  • Unknown properties are refused.
Example: Synthetic published fixture
{
  "data": [
    {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "operator_ref": "000123",
      "name": "Example Foods Ltd",
      "commodities": 1,
      "months": 1,
      "first_period": "2026-06",
      "last_period": "2026-06",
      "flows": [
        "import"
      ],
      "lineage": {
        "method": "aggregated",
        "basis": "published_operator_links",
        "counts": {
          "commodities": "distinct commodity_scheme and commodity_code",
          "months": "distinct published period",
          "links": "distinct published link including its lineage and revision"
        }
      },
      "codes": [
        {
          "commodity_scheme": "CN8",
          "commodity_code": "02071410"
        }
      ],
      "codes_truncated": false
    }
  ],
  "meta": {
    "count": 1,
    "limit": 100,
    "next_cursor": null,
    "release": {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

404Resource or requested published month not found. Foreign export keys also receive 404.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

409Publication changed, organisation already has five active exports, or export is not downloadable. Restart data pagination after publication_changed.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "publication_changed",
    "message": "The publication changed during this request. Restart pagination.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

CSV / Parquet export columns, in order

CSV represents null as an empty field. Parquet uses the nullable types below. Source codes remain strings.

  1. sourceNullable(String)
  2. reporterNullable(String)
  3. operator_refNullable(String)
  4. nameNullable(String)
  5. commoditiesNullable(Int64)
  6. monthsNullable(Int64)
  7. first_periodNullable(String)
  8. last_periodNullable(String)
  9. flowsNullable(String)
  10. codesNullable(String)
  11. codes_truncatedNullable(Bool)
  12. methodNullable(String)
  13. basisNullable(String)
  14. countsNullable(String)
  15. release_sourceNullable(String)
  16. release_periodNullable(String)
  17. release_generationNullable(String)
  18. reference_revisionNullable(String)
GET/operators/{source}/{ref}read scopeGet a declared operator

Returns latest published directory attributes and aggregate counts over loaded months. The composite identity is source plus ref. Country and address are verbatim directory strings, not verified registry identities. No query parameters or body.

curl --fail-with-body --include 'https://api.tradaro.com/v1/operators/hmrc_uktradeinfo/000123' \
  --header "Authorization: Bearer $TRADARO_API_KEY"

Parameters

ParameterLocationDescription and constraints
sourceRequiredpath

Published source identifier. Other sources return 404.

Source

  • Value: "hmrc_uktradeinfo"

Example: "hmrc_uktradeinfo"

refRequiredpath

Trader-directory source identifier, not a company registration number.

OperatorRef

Source-scoped trader directory identifier, kept as text, including leading zeroes. Not a company registration number.

  • Pattern: "^[0-9]{1,12}$"

Example: "000123"

Responses

200Successful response.

application/json

OperatorResponse

  • Unknown properties are refused.
Example: Synthetic published fixture
{
  "data": {
    "source": "hmrc_uktradeinfo",
    "reporter": "GB",
    "operator_ref": "000123",
    "name": "Example Foods Ltd",
    "commodities": 1,
    "months": 1,
    "first_period": "2026-06",
    "last_period": "2026-06",
    "flows": [
      "import"
    ],
    "lineage": {
      "method": "aggregated",
      "basis": "published_operator_links",
      "counts": {
        "commodities": "distinct commodity_scheme and commodity_code",
        "months": "distinct published period",
        "links": "distinct published link including its lineage and revision"
      }
    },
    "address_lines": [
      "1 Example Road"
    ],
    "postal_code": "AB1 2CD",
    "country": "United Kingdom",
    "attributes_period": "2026-06",
    "links": 1
  },
  "meta": {
    "count": 1,
    "release": {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

404Resource or requested published month not found. Foreign export keys also receive 404.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

409Publication changed, organisation already has five active exports, or export is not downloadable. Restart data pagination after publication_changed.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "publication_changed",
    "message": "The publication changed during this request. Restart pagination.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Trade

Published trade cells, commodity references and partner codes.

GET/commodities/{scheme}/{code}read scopeGet a nomenclature entry

Reads the loaded reference independently of trade activity. Supports actual CN8, HS6 and residual HS2 entries; does not synthesize an HS6 from a prefix. period selects effective crosswalk validity and must be published. parent_codes preserve original forms such as 02----. Unknown entries return 404. meta.reference_revision fingerprints the reference version. No request body.

curl --fail-with-body --include 'https://api.tradaro.com/v1/commodities/CN8/02071410' \
  --header "Authorization: Bearer $TRADARO_API_KEY"

Parameters

ParameterLocationDescription and constraints
schemeRequiredpath

Loaded nomenclature scheme; no implicit conversion.

CommodityScheme

  • Allowed: "CN8", "HS6", "HS2"

Example: "CN8"

codeRequiredpath

Eight digits for CN8, six for HS6, or two digits with optional six hyphens for HS2. Keep leading zeroes.

CommodityCode

CN8: eight digits; HS6: six digits; HS2: two digits, optionally followed by six hyphens. Codes are never converted implicitly.

  • Pattern: "^(?:[0-9]{8}|[0-9]{6}|[0-9]{2}(?:------)?)$"

Example: "02071410"

reporterOptionalquery

Reporter market; defaults to GB. Entitlements are enforced before warehouse reads.

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
  • Default: "GB"

Example: "GB"

periodOptionalquery

Published month; defaults to the latest release. An absent release is not inferred from another month.

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"

Example: "2026-06"

Responses

200Successful response.

application/json

CommodityResponse

  • Unknown properties are refused.
Example: Synthetic published fixture
{
  "data": {
    "source": "hmrc_uktradeinfo",
    "commodity_scheme": "CN8",
    "commodity_code": "02071410",
    "description": "Example frozen poultry cuts",
    "parent_codes": [
      "020714",
      "0207",
      "02"
    ],
    "reference_batch": "ref",
    "alt_scheme": null,
    "alt_code": null,
    "hs6": "020714",
    "hs6_mappings": [
      {
        "source": "hmrc_uktradeinfo",
        "reference_batch": "ref",
        "hs6": "020714",
        "hs_version": "2022",
        "valid_from": null,
        "valid_to": null
      }
    ]
  },
  "meta": {
    "count": 1,
    "period": "2026-06",
    "reference_revision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "release": {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

404Resource or requested published month not found. Foreign export keys also receive 404.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

409Publication changed, organisation already has five active exports, or export is not downloadable. Restart data pagination after publication_changed.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "publication_changed",
    "message": "The publication changed during this request. Restart pagination.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

GET/flowsread scopeList published trade cells

Reads source cells without aggregation, including duplicate components and suppressed nulls. Defaults to CN8 in the latest published month; from defaults to to. Inclusive range is at most 120 calendar months and both endpoints must be published. Only published months inside the range are read. partner alone means ISO alpha-2, resolved separately for each month; partner_scheme plus partner means an exact original code. ISO filtering adds meta.reference_revision. No request body.

curl --fail-with-body --include 'https://api.tradaro.com/v1/flows' \
  --header "Authorization: Bearer $TRADARO_API_KEY"

Parameters

ParameterLocationDescription and constraints
reporterOptionalquery

Reporter market; defaults to GB. Entitlements are enforced before warehouse reads.

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
  • Default: "GB"

Example: "GB"

commodityOptionalquery

Exact commodity code in commodity_scheme; omit for every loaded code in that scheme.

CommodityCode

CN8: eight digits; HS6: six digits; HS2: two digits, optionally followed by six hyphens. Codes are never converted implicitly.

  • Pattern: "^(?:[0-9]{8}|[0-9]{6}|[0-9]{2}(?:------)?)$"

Example: "02071410"

commodity_schemeOptionalquery

Scheme to read, even when commodity is omitted. Only actual loaded rows are returned.

CommodityScheme

  • Default: "CN8"
  • Allowed: "CN8", "HS6", "HS2"
partnerOptionalquery

Without partner_scheme, an uppercase ISO alpha-2 code matched through the effective geographic reference for each month. With partner_scheme, an exact original source code, including residual codes.

GeoCode

Original source code, including residual or aggregate codes. Does not imply an ISO identity.

  • Pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$"

Example: "FR"

partner_schemeOptionalquery

Requires partner. Selects its original source scheme instead of ISO lookup; use the scheme returned by /partners.

GeoScheme

  • Pattern: "^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$"

Example: "uktradeinfo:CountryId"

flowOptionalquery

Exact trade direction; omitted returns both.

Flow

  • Allowed: "import", "export"

Example: "import"

fromOptionalquery

Inclusive published lower month. For flows, defaults to to; for operator links, defaults to the earliest published month.

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
toOptionalquery

Inclusive published upper month; defaults to the latest release.

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
limitOptionalquery

Maximum rows per page, 1–500 (default 100). Send one canonical decimal value, without a leading zero; array values are refused.

integer

  • Minimum: 1
  • Maximum: 500
  • Default: 100

Example: 100

cursorOptionalquery

Opaque token from meta.next_cursor. Keep all filters unchanged; null means the end. Do not decode or construct tokens.

Cursor

Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change.

  • Maximum characters: 4096
  • Pattern: "^[A-Za-z0-9_-]+$"

Responses

200Successful response.

application/json

FlowsResponse

  • Unknown properties are refused.
Example: Synthetic published fixture
{
  "data": [
    {
      "source": "hmrc_uktradeinfo",
      "batch_key": "2026-06",
      "reporter_geo_scheme": "iso3166-1:alpha2",
      "reporter_geo_code": "GB",
      "period": "2026-06",
      "flow": "import",
      "commodity_scheme": "CN8",
      "commodity_code": "02071410",
      "partner_geo_scheme": "uktradeinfo:CountryId",
      "partner_geo_code": "001",
      "location_code": "",
      "currency": "GBP",
      "tier": "T1",
      "method": "declared",
      "confidence": "A",
      "revision": 1,
      "component": 1,
      "suppressed": false,
      "value": 1250.5,
      "net_mass_kg": 100,
      "supplementary_unit": null
    }
  ],
  "meta": {
    "count": 1,
    "limit": 100,
    "next_cursor": null,
    "release": {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "from": "2026-06",
    "to": "2026-06",
    "periods": [
      "2026-06"
    ]
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

404Resource or requested published month not found. Foreign export keys also receive 404.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

409Publication changed, organisation already has five active exports, or export is not downloadable. Restart data pagination after publication_changed.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "publication_changed",
    "message": "The publication changed during this request. Restart pagination.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

CSV / Parquet export columns, in order

CSV represents null as an empty field. Parquet uses the nullable types below. Source codes remain strings.

  1. sourceNullable(String)
  2. batch_keyNullable(String)
  3. reporter_geo_schemeNullable(String)
  4. reporter_geo_codeNullable(String)
  5. periodNullable(String)
  6. flowNullable(String)
  7. commodity_schemeNullable(String)
  8. commodity_codeNullable(String)
  9. partner_geo_schemeNullable(String)
  10. partner_geo_codeNullable(String)
  11. location_codeNullable(String)
  12. currencyNullable(String)
  13. tierNullable(String)
  14. methodNullable(String)
  15. confidenceNullable(String)
  16. revisionNullable(Int64)
  17. componentNullable(Int64)
  18. suppressedNullable(Bool)
  19. valueNullable(Float64)
  20. net_mass_kgNullable(Float64)
  21. supplementary_unitNullable(Float64)
  22. release_sourceNullable(String)
  23. release_periodNullable(String)
  24. release_generationNullable(String)
  25. reference_revisionNullable(String)
GET/partnersread scopeList published partner codes

Returns partner identities actually present in the selected month across supported commodity schemes. Labels and optional ISO identities come from effective geographic references. Residual or unmapped codes are retained. Ordered by original scheme and code. No request body.

curl --fail-with-body --include 'https://api.tradaro.com/v1/partners' \
  --header "Authorization: Bearer $TRADARO_API_KEY"

Parameters

ParameterLocationDescription and constraints
reporterOptionalquery

Reporter market; defaults to GB. Entitlements are enforced before warehouse reads.

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
  • Default: "GB"

Example: "GB"

periodOptionalquery

Published month; defaults to the latest release. An absent release is not inferred from another month.

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"

Example: "2026-06"

limitOptionalquery

Maximum rows per page, 1–500 (default 100). Send one canonical decimal value, without a leading zero; array values are refused.

integer

  • Minimum: 1
  • Maximum: 500
  • Default: 100

Example: 100

cursorOptionalquery

Opaque token from meta.next_cursor. Keep all filters unchanged; null means the end. Do not decode or construct tokens.

Cursor

Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change.

  • Maximum characters: 4096
  • Pattern: "^[A-Za-z0-9_-]+$"

Responses

200Successful response.

application/json

PartnersResponse

  • Unknown properties are refused.
Example: Synthetic published fixture
{
  "data": [
    {
      "source": "hmrc_uktradeinfo",
      "partner_geo_scheme": "uktradeinfo:CountryId",
      "partner_geo_code": "001",
      "name": "France",
      "iso_alpha2": "FR",
      "reference_batch": "ref",
      "valid_from": null,
      "valid_to": null
    }
  ],
  "meta": {
    "count": 1,
    "limit": 100,
    "next_cursor": null,
    "release": {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "period": "2026-06",
    "reference_revision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

404Resource or requested published month not found. Foreign export keys also receive 404.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

409Publication changed, organisation already has five active exports, or export is not downloadable. Restart data pagination after publication_changed.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "publication_changed",
    "message": "The publication changed during this request. Restart pagination.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

CSV / Parquet export columns, in order

CSV represents null as an empty field. Parquet uses the nullable types below. Source codes remain strings.

  1. sourceNullable(String)
  2. partner_geo_schemeNullable(String)
  3. partner_geo_codeNullable(String)
  4. nameNullable(String)
  5. iso_alpha2Nullable(String)
  6. reference_batchNullable(String)
  7. valid_fromNullable(String)
  8. valid_toNullable(String)
  9. release_sourceNullable(String)
  10. release_periodNullable(String)
  11. release_generationNullable(String)
  12. reference_revisionNullable(String)

Exports

Asynchronous CSV and Parquet files scoped to the creating key.

POST/exportsbulk scopeCreate an asynchronous export

Creates an asynchronous CSV or Parquet export of one supported list endpoint. Requires bulk scope and an effective export allowance; read scope is not additionally required. params is a JSON object of the endpoint’s string filters; omit limit and cursor. No URL query parameters. JSON body is at most 4096 bytes. row_limit defaults to 100000 and is capped by current organisation rights. At most five active exports per organisation, shared with web exports. Data and references are pinned during generation; changes fail the job rather than mix versions. The creating key alone may poll or download; revocation and changed entitlements apply immediately. Jobs expire after 24 hours, with a 30-minute processing deadline. CSV is UTF-8 with BOM, a header and quoted fields; null is empty, booleans are true/false, arrays and objects are JSON text. Potential formula strings receive an apostrophe prefix; Parquet retains raw strings, native nullable numbers/booleans and nulls. Source codes remain text. Fixed columns are listed in each exportable operation’s x-export-columns; each row includes release_source, release_period, release_generation and nullable reference_revision. Files are bounded to 256 MiB; empty results produce a valid file with the fixed schema. Poll according to Retry-After; failed/expired states report error_code.

curl --fail-with-body --include --request POST 'https://api.tradaro.com/v1/exports' \
  --header "Authorization: Bearer $TRADARO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"endpoint":"/flows","params":{"commodity":"02071410"},"format":"csv","row_limit":2}'

Parameters

No path or query parameters.

Request body · required

A supported list path, its string filter object, output format and optional row cap.

application/json

ExportRequest

Example: Export two published commodity cells
{
  "endpoint": "/flows",
  "params": {
    "commodity": "02071410"
  },
  "format": "csv",
  "row_limit": 2
}
Example: Export loaded reporters
{
  "endpoint": "/reporters",
  "params": {},
  "format": "parquet",
  "row_limit": 10
}

Responses

202Accepted; process asynchronously and poll the Location URL.

application/json

ExportResponse

  • Unknown properties are refused.
Example: pending
{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "pending",
    "format": "csv",
    "endpoint": "/flows",
    "cap": 2,
    "rows": 0,
    "bytes": 0,
    "truncated": false,
    "created_at": "2026-09-11T00:00:00.000000Z",
    "expires_at": "2026-09-12T00:00:00Z",
    "finished_at": null,
    "error_code": null,
    "status_url": "/v1/exports/11111111-1111-4111-8111-111111111111",
    "download_url": null
  },
  "meta": {
    "count": 1,
    "release": {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
Location

Relative URL of the newly created export status resource.

string

  • Pattern: "^/v1/exports/[a-f0-9-]{36}$"
Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

404Resource or requested published month not found. Foreign export keys also receive 404.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

409Publication changed, organisation already has five active exports, or export is not downloadable. Restart data pagination after publication_changed.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "publication_changed",
    "message": "The publication changed during this request. Restart pagination.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

413Request body exceeds 4096 bytes, or export exceeds its bound.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "payload_too_large",
    "message": "The request body is too large.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

415Export creation requires application/json.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "unsupported_media_type",
    "message": "Use application/json for this request.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

GET/exports/{id}bulk scopeGet export status

Poll with the creating key. Status is pending, running, completed, failed or expired. A completed response contains download_url. Error details are sanitised in error_code. No query parameters or body.

curl --fail-with-body --include 'https://api.tradaro.com/v1/exports/11111111-1111-4111-8111-111111111111' \
  --header "Authorization: Bearer $TRADARO_API_KEY"

Parameters

ParameterLocationDescription and constraints
idRequiredpath

Export UUID returned by creation; only its creating key can access it.

string

  • Format: "uuid"

Example: "11111111-1111-4111-8111-111111111111"

Responses

200Successful response.

application/json

ExportResponse

  • Unknown properties are refused.
Example: completed
{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "completed",
    "format": "csv",
    "endpoint": "/flows",
    "cap": 2,
    "rows": 2,
    "bytes": 2048,
    "truncated": true,
    "created_at": "2026-09-11T00:00:00.000000Z",
    "expires_at": "2026-09-12T00:00:00Z",
    "finished_at": "2026-09-11T00:01:00Z",
    "error_code": null,
    "status_url": "/v1/exports/11111111-1111-4111-8111-111111111111",
    "download_url": "/v1/exports/11111111-1111-4111-8111-111111111111/download"
  },
  "meta": {
    "count": 1,
    "release": {
      "source": "hmrc_uktradeinfo",
      "reporter": "GB",
      "period": "2026-06",
      "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

404Resource or requested published month not found. Foreign export keys also receive 404.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

409Publication changed, organisation already has five active exports, or export is not downloadable. Restart data pagination after publication_changed.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "publication_changed",
    "message": "The publication changed during this request. Restart pagination.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

GET/exports/{id}/downloadbulk scopeDownload an export

Download the retained snapshot with its creating key. Requires a completed, unexpired export and current entitlement; otherwise 409 or 403. Another key, including one in the same organisation, receives 404. Returns file bytes, not a JSON envelope or signed URL. X-Tradaro-Content-SHA256 verifies the exact bytes. No query parameters or body.

curl --fail-with-body --dump-header export.headers 'https://api.tradaro.com/v1/exports/11111111-1111-4111-8111-111111111111/download' \
  --header "Authorization: Bearer $TRADARO_API_KEY" \
  --output export.csv

Parameters

ParameterLocationDescription and constraints
idRequiredpath

Export UUID returned by creation; only its creating key can access it.

string

  • Format: "uuid"

Example: "11111111-1111-4111-8111-111111111111"

Responses

200UTF-8 CSV or typed Parquet file, at most 256 MiB. Content-Disposition supplies the filename.

text/csv

string

application/vnd.apache.parquet

File bytes in this media type.

Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

X-Tradaro-Release

Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.

string

  • Pattern: "^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"
X-Tradaro-Quota-Limit

Daily request allowance for the key; unlimited when the effective offer has no daily cap.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Remaining

Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.

string

  • Pattern: "^(?:[0-9]+|unlimited)$"
X-Tradaro-Quota-Reset

UTC instant at the next daily request-window reset.

Instant

  • Format: "date-time"
X-RateLimit-Limit

Maximum authenticated requests per key in a minute.

string

  • Value: "60"
X-RateLimit-Remaining

Requests left in the key’s current minute after this call.

string

  • Pattern: "^[0-9]+$"
X-RateLimit-Reset

UTC instant when the current minute window resets.

Instant

  • Format: "date-time"
X-Content-Type-Options

Disables MIME sniffing.

string

  • Value: "nosniff"
Content-Disposition

Attachment filename tradaro-{export UUID}.csv or .parquet.

string

X-Tradaro-Content-SHA256

SHA-256 of the exact downloaded bytes.

string

  • Pattern: "^[a-f0-9]{64}$"
400Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

401Missing, malformed, unknown or revoked Bearer key.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer credential is required.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

WWW-Authenticate

Bearer authentication is required.

string

  • Value: "Bearer"
403Effective API rights, required key scope, market entitlement or differences entitlement deny this request.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "scope_denied",
    "message": "The API key does not have the required permission.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

404Resource or requested published month not found. Foreign export keys also receive 404.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

409Publication changed, organisation already has five active exports, or export is not downloadable. Restart data pagination after publication_changed.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "publication_changed",
    "message": "The publication changed during this request. Restart pagination.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

429Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_rate_limited",
    "message": "The API request rate limit has been reached.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Retry-After

Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.

string

  • Pattern: "^[1-9][0-9]*$"
503Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.

application/json

Error

  • Unknown properties are refused.
Example: example
{
  "error": {
    "code": "api_unavailable",
    "message": "The API is temporarily unavailable.",
    "request_id": "11111111-1111-4111-8111-111111111111"
  }
}
Response headers
X-Request-ID

Server-generated request UUID. Include it when reporting an error.

string

  • Format: "uuid"
Cache-Control

Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.

string

Shared schemas

Follow schema links from the operation reference. Required fields may still be nullable when their type includes null.

Sourcestring

string

  • Value: "hmrc_uktradeinfo"
Reporterstring

string

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
Periodstring

string

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
Generationstring

string

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
ReferenceRevisionstring

string

SHA-256 fingerprint of the loaded reference versions used by this response. Separate from the trade release generation.

  • Pattern: "^[a-f0-9]{64}$"
OperatorRefstring

string

Source-scoped trader directory identifier, kept as text, including leading zeroes. Not a company registration number.

  • Pattern: "^[0-9]{1,12}$"
Flowstring

string

  • Allowed: "import", "export"
CommoditySchemestring

string

  • Allowed: "CN8", "HS6", "HS2"
CommodityCodestring

string

CN8: eight digits; HS6: six digits; HS2: two digits, optionally followed by six hyphens. Codes are never converted implicitly.

  • Pattern: "^(?:[0-9]{8}|[0-9]{6}|[0-9]{2}(?:------)?)$"
GeoSchemestring

string

  • Pattern: "^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$"
GeoCodestring

string

Original source code, including residual or aggregate codes. Does not imply an ISO identity.

  • Pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$"
Cursorstring

string

Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change.

  • Maximum characters: 4096
  • Pattern: "^[A-Za-z0-9_-]+$"
Instantstring

string

  • Format: "date-time"
Countinteger

integer

  • Minimum: 0
  • Maximum: 9007199254740991
UInt32integer

integer

  • Minimum: 0
  • Maximum: 4294967295
ReleaseIdentityobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
reporterRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
generationRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
DiffKindstring

string

  • Allowed: "new_operator", "operator_returned", "new_operator_commodity", "new_partner_for_commodity", "commodity_value_change"
ReleaseSummaryobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
new_operatorRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
operator_returnedRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
new_operator_commodityRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
new_partner_for_commodityRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
commodity_value_changeRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
Licenceobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
nameRequired

string

  • Value: "Open Government Licence v3.0"
urlRequired

string

  • Value: "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
attributionRequired

string

  • Value: "Contains public sector information licensed under the Open Government Licence v3.0. HMRC does not endorse Tradaro."
ReporterRecordobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
reporterRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
nameRequired

string

sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
latest_periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
generationRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
loaded_atRequired

Instant

  • Format: "date-time"
licenceRequired

Licence

  • Unknown properties are refused.
ReleaseRecordobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
reporterRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
previous_periodRequired

string | null

Any of

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"

null

history_startRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
generationRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
summaryRequired

ReleaseSummary

  • Unknown properties are refused.
loaded_atRequired

Instant

  • Format: "date-time"
diff_computed_atRequired

Instant

  • Format: "date-time"
observed_atRequired

Instant

  • Format: "date-time"
CountMetaobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
countRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
PageMetaobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
countRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
limitRequired

integer

  • Minimum: 1
  • Maximum: 500
next_cursorRequired

string | null

Any of

Cursor

Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change.

  • Maximum characters: 4096
  • Pattern: "^[A-Za-z0-9_-]+$"

null

PublishedMetaobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
countRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
releaseRequired

ReleaseIdentity

  • Unknown properties are refused.
PublishedPageMetaobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
countRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
limitRequired

integer

  • Minimum: 1
  • Maximum: 500
next_cursorRequired

string | null

Any of

Cursor

Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change.

  • Maximum characters: 4096
  • Pattern: "^[A-Za-z0-9_-]+$"

null

releaseRequired

ReleaseIdentity

  • Unknown properties are refused.
FlowMetaobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
countRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
limitRequired

integer

  • Minimum: 1
  • Maximum: 500
next_cursorRequired

string | null

Any of

Cursor

Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change.

  • Maximum characters: 4096
  • Pattern: "^[A-Za-z0-9_-]+$"

null

fromRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
toRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
periodsRequired

array<string>

  • Minimum items: 1
  • Maximum items: 120
Array items

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
reference_revisionOptional

ReferenceRevision

SHA-256 fingerprint of the loaded reference versions used by this response. Separate from the trade release generation.

  • Pattern: "^[a-f0-9]{64}$"
releaseRequired

ReleaseIdentity

  • Unknown properties are refused.
ReferenceMetaobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
countRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
reference_revisionRequired

ReferenceRevision

SHA-256 fingerprint of the loaded reference versions used by this response. Separate from the trade release generation.

  • Pattern: "^[a-f0-9]{64}$"
releaseRequired

ReleaseIdentity

  • Unknown properties are refused.
PartnerMetaobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
countRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
limitRequired

integer

  • Minimum: 1
  • Maximum: 500
next_cursorRequired

string | null

Any of

Cursor

Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change.

  • Maximum characters: 4096
  • Pattern: "^[A-Za-z0-9_-]+$"

null

periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
reference_revisionRequired

ReferenceRevision

SHA-256 fingerprint of the loaded reference versions used by this response. Separate from the trade release generation.

  • Pattern: "^[a-f0-9]{64}$"
releaseRequired

ReleaseIdentity

  • Unknown properties are refused.
DiffMetaobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
countRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
limitRequired

integer

  • Minimum: 1
  • Maximum: 500
next_cursorRequired

string | null

Any of

Cursor

Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change.

  • Maximum characters: 4096
  • Pattern: "^[A-Za-z0-9_-]+$"

null

totalRequired

Count

  • Minimum: 0
  • Maximum: 9007199254740991
releaseRequired

ReleaseIdentity

  • Unknown properties are refused.
OperatorSearchRecordobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
reporterRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
operator_refRequired

OperatorRef

Source-scoped trader directory identifier, kept as text, including leading zeroes. Not a company registration number.

  • Pattern: "^[0-9]{1,12}$"
nameRequired

string

  • Maximum characters: 1024
commoditiesRequired

integer

  • Minimum: 1
  • Maximum: 4294967295
monthsRequired

integer

  • Minimum: 1
  • Maximum: 2000
first_periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
last_periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
flowsRequired

array<string>

  • Minimum items: 1
  • Maximum items: 2
  • Items must be unique.
Array items

Flow

  • Allowed: "import", "export"
lineageRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
methodRequired

string

  • Value: "aggregated"
basisRequired

string

  • Value: "published_operator_links"
countsRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
commoditiesRequired

string

  • Value: "distinct commodity_scheme and commodity_code"
monthsRequired

string

  • Value: "distinct published period"
linksRequired

string

  • Value: "distinct published link including its lineage and revision"
codesRequired

array<object>

  • Minimum items: 1
  • Maximum items: 6
Array items

object

Only the published trader-directory schemes CN8 and residual HS2 are returned.

  • Unknown properties are refused.
PropertyPresenceType and constraints
commodity_schemeRequired

string

  • Allowed: "CN8", "HS2"
commodity_codeRequired

CommodityCode

CN8: eight digits; HS6: six digits; HS2: two digits, optionally followed by six hyphens. Codes are never converted implicitly.

  • Pattern: "^(?:[0-9]{8}|[0-9]{6}|[0-9]{2}(?:------)?)$"

All of

JSON

Conditional validation rule
{
  "if": {
    "properties": {
      "commodity_scheme": {
        "const": "CN8"
      }
    }
  },
  "then": {
    "properties": {
      "commodity_code": {
        "type": "string",
        "pattern": "^[0-9]{8}$"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "properties": {
      "commodity_scheme": {
        "const": "HS6"
      }
    }
  },
  "then": {
    "properties": {
      "commodity_code": {
        "type": "string",
        "pattern": "^[0-9]{6}$"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "properties": {
      "commodity_scheme": {
        "const": "HS2"
      }
    }
  },
  "then": {
    "properties": {
      "commodity_code": {
        "type": "string",
        "pattern": "^[0-9]{2}(?:------)?$"
      }
    }
  }
}
codes_truncatedRequired

boolean

OperatorProfileobject

object

Declared directory attributes from attributes_period. No inferred registry match, company turnover or shipment values.

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
reporterRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
operator_refRequired

OperatorRef

Source-scoped trader directory identifier, kept as text, including leading zeroes. Not a company registration number.

  • Pattern: "^[0-9]{1,12}$"
nameRequired

string

  • Maximum characters: 1024
commoditiesRequired

integer

  • Minimum: 1
  • Maximum: 4294967295
monthsRequired

integer

  • Minimum: 1
  • Maximum: 2000
first_periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
last_periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
flowsRequired

array<string>

  • Minimum items: 1
  • Maximum items: 2
  • Items must be unique.
Array items

Flow

  • Allowed: "import", "export"
lineageRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
methodRequired

string

  • Value: "aggregated"
basisRequired

string

  • Value: "published_operator_links"
countsRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
commoditiesRequired

string

  • Value: "distinct commodity_scheme and commodity_code"
monthsRequired

string

  • Value: "distinct published period"
linksRequired

string

  • Value: "distinct published link including its lineage and revision"
address_linesRequired

array<string>

Array items

string

  • Maximum characters: 1024
postal_codeRequired

string

  • Maximum characters: 1024
countryRequired

string

  • Maximum characters: 1024
attributes_periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
linksRequired

integer

  • Minimum: 1
  • Maximum: 9007199254740991
TradeFlowobject

object

One published source cell. Amount is in currency; mass is kilograms. Null is not zero. All measures are null for suppressed cells; non-suppressed value is a finite number. Negative adjustments and duplicate cells are preserved.

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
batch_keyRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
reporter_geo_schemeRequired

string

  • Value: "iso3166-1:alpha2"
reporter_geo_codeRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
flowRequired

Flow

  • Allowed: "import", "export"
commodity_schemeRequired

CommodityScheme

  • Allowed: "CN8", "HS6", "HS2"
commodity_codeRequired

CommodityCode

CN8: eight digits; HS6: six digits; HS2: two digits, optionally followed by six hyphens. Codes are never converted implicitly.

  • Pattern: "^(?:[0-9]{8}|[0-9]{6}|[0-9]{2}(?:------)?)$"
partner_geo_schemeRequired

GeoScheme

  • Pattern: "^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$"
partner_geo_codeRequired

GeoCode

Original source code, including residual or aggregate codes. Does not imply an ISO identity.

  • Pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$"
location_codeRequired

string

  • Maximum characters: 128
currencyRequired

string

  • Pattern: "^[A-Z]{3}$"
tierRequired

string

  • Value: "T1"
methodRequired

string

  • Value: "declared"
confidenceRequired

string

  • Value: "A"
revisionRequired

UInt32

  • Minimum: 0
  • Maximum: 4294967295
componentRequired

integer

Stable ordinal within identical dimensions and revision; preserves distinct or duplicate published cells without aggregation.

  • Minimum: 1
  • Maximum: 9007199254740991
suppressedRequired

boolean

valueRequired

number | null

net_mass_kgRequired

number | null

supplementary_unitRequired

number | null

All of

JSON

Conditional validation rule
{
  "if": {
    "properties": {
      "suppressed": {
        "const": true
      }
    }
  },
  "then": {
    "properties": {
      "value": {
        "type": "null"
      },
      "net_mass_kg": {
        "type": "null"
      },
      "supplementary_unit": {
        "type": "null"
      }
    }
  },
  "else": {
    "properties": {
      "value": {
        "type": "number"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "properties": {
      "commodity_scheme": {
        "const": "CN8"
      }
    }
  },
  "then": {
    "properties": {
      "commodity_code": {
        "type": "string",
        "pattern": "^[0-9]{8}$"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "properties": {
      "commodity_scheme": {
        "const": "HS6"
      }
    }
  },
  "then": {
    "properties": {
      "commodity_code": {
        "type": "string",
        "pattern": "^[0-9]{6}$"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "properties": {
      "commodity_scheme": {
        "const": "HS2"
      }
    }
  },
  "then": {
    "properties": {
      "commodity_code": {
        "type": "string",
        "pattern": "^[0-9]{2}(?:------)?$"
      }
    }
  }
}
Hs6Mappingobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
reference_batchRequired

string

  • Minimum characters: 1
  • Maximum characters: 128
hs6Required

string | null

Any of

string

  • Pattern: "^[0-9]{6}$"

null

hs_versionRequired

string | null

Any of

string

  • Maximum characters: 64

null

valid_fromRequired

string | null

Any of

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"

null

valid_toRequired

string | null

Any of

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"

null

Commodityobject

object

Loaded nomenclature entry independent of trade activity. Parent and residual codes remain verbatim; a parent is not implicitly an HS6. hs6 is null when no unique mapping exists, except a loaded HS6 entry identifies itself. Validity boundaries are inclusive; null means an open boundary.

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
commodity_schemeRequired

CommodityScheme

  • Allowed: "CN8", "HS6", "HS2"
commodity_codeRequired

CommodityCode

CN8: eight digits; HS6: six digits; HS2: two digits, optionally followed by six hyphens. Codes are never converted implicitly.

  • Pattern: "^(?:[0-9]{8}|[0-9]{6}|[0-9]{2}(?:------)?)$"
descriptionRequired

string

  • Maximum characters: 16384
parent_codesRequired

array<string>

  • Maximum items: 16
Array items

string

  • Pattern: "^(?:[A-Za-z0-9-]{2}|[A-Za-z0-9-]{4}|[A-Za-z0-9-]{6})$"
reference_batchRequired

string

  • Minimum characters: 1
  • Maximum characters: 128
alt_schemeRequired

string | null

Any of

string

  • Maximum characters: 64

null

alt_codeRequired

string | null

Any of

string

  • Maximum characters: 128

null

hs6Required

string | null

Any of

string

  • Pattern: "^[0-9]{6}$"

null

hs6_mappingsRequired

array<object>

  • Maximum items: 500
Array items

Hs6Mapping

  • Unknown properties are refused.

All of

JSON

Conditional validation rule
{
  "if": {
    "properties": {
      "commodity_scheme": {
        "const": "CN8"
      }
    }
  },
  "then": {
    "properties": {
      "commodity_code": {
        "type": "string",
        "pattern": "^[0-9]{8}$"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "properties": {
      "commodity_scheme": {
        "const": "HS6"
      }
    }
  },
  "then": {
    "properties": {
      "commodity_code": {
        "type": "string",
        "pattern": "^[0-9]{6}$"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "properties": {
      "commodity_scheme": {
        "const": "HS2"
      }
    }
  },
  "then": {
    "properties": {
      "commodity_code": {
        "type": "string",
        "pattern": "^[0-9]{2}(?:------)?$"
      }
    }
  }
}
Partnerobject

object

A partner code present in the selected month, enriched only by the effective loaded mapping. Unmapped and residual codes remain present with null labels or ISO codes. Null validity boundaries are open.

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
partner_geo_schemeRequired

GeoScheme

  • Pattern: "^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$"
partner_geo_codeRequired

GeoCode

Original source code, including residual or aggregate codes. Does not imply an ISO identity.

  • Pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$"
nameRequired

string | null

Any of

string

  • Maximum characters: 2048

null

iso_alpha2Required

string | null

Any of

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"

null

reference_batchRequired

string | null

Any of

string

  • Maximum characters: 128

null

valid_fromRequired

string | null

Any of

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"

null

valid_toRequired

string | null

Any of

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"

null

NewOperatorDiffobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
reporterRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
generationRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
kindRequired

string

  • Value: "new_operator"
subjectRequired

string

  • Minimum characters: 1
  • Maximum characters: 4096
detailRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
operator_refRequired

OperatorRef

Source-scoped trader directory identifier, kept as text, including leading zeroes. Not a company registration number.

  • Pattern: "^[0-9]{1,12}$"
operator_nameRequired

string

  • Maximum characters: 1024
tierRequired

null

methodRequired

string

  • Value: "derived"
confidenceRequired

null

revisionRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
basisRequired

string

  • Value: "monthly-declared-cn8-v1"
OperatorReturnedDiffobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
reporterRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
generationRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
kindRequired

string

  • Value: "operator_returned"
subjectRequired

string

  • Minimum characters: 1
  • Maximum characters: 4096
detailRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
operator_refRequired

OperatorRef

Source-scoped trader directory identifier, kept as text, including leading zeroes. Not a company registration number.

  • Pattern: "^[0-9]{1,12}$"
operator_nameRequired

string

  • Maximum characters: 1024
tierRequired

null

methodRequired

string

  • Value: "derived"
confidenceRequired

null

revisionRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
basisRequired

string

  • Value: "monthly-declared-cn8-v1"
NewOperatorCommodityDiffobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
reporterRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
generationRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
kindRequired

string

  • Value: "new_operator_commodity"
subjectRequired

string

  • Minimum characters: 1
  • Maximum characters: 4096
detailRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
operator_refRequired

OperatorRef

Source-scoped trader directory identifier, kept as text, including leading zeroes. Not a company registration number.

  • Pattern: "^[0-9]{1,12}$"
operator_nameRequired

string

  • Maximum characters: 1024
commodity_codeRequired

string

  • Pattern: "^[0-9]{8}$"
commodity_schemeRequired

string

  • Value: "CN8"
flowRequired

Flow

  • Allowed: "import", "export"
tierRequired

null

methodRequired

string

  • Value: "derived"
confidenceRequired

null

revisionRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
basisRequired

string

  • Value: "monthly-declared-cn8-v1"
NewPartnerForCommodityDiffobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
reporterRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
generationRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
kindRequired

string

  • Value: "new_partner_for_commodity"
subjectRequired

string

  • Minimum characters: 1
  • Maximum characters: 4096
detailRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
commodity_codeRequired

string

  • Pattern: "^[0-9]{8}$"
commodity_schemeRequired

string

  • Value: "CN8"
flowRequired

Flow

  • Allowed: "import", "export"
partner_geo_schemeRequired

string

  • Minimum characters: 1
  • Maximum characters: 1024
partner_geo_codeRequired

string

  • Minimum characters: 1
  • Maximum characters: 1024
tierRequired

null

methodRequired

string

  • Value: "derived"
confidenceRequired

null

revisionRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
basisRequired

string

  • Value: "monthly-declared-cn8-v1"
CommodityValueChangeDiffobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
sourceRequired

Source

  • Value: "hmrc_uktradeinfo"
reporterRequired

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
periodRequired

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
generationRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
kindRequired

string

  • Value: "commodity_value_change"
subjectRequired

string

  • Minimum characters: 1
  • Maximum characters: 4096
detailRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
commodity_codeRequired

string

  • Pattern: "^[0-9]{8}$"
commodity_schemeRequired

string

  • Value: "CN8"
flowRequired

Flow

  • Allowed: "import", "export"
currencyRequired

string

  • Pattern: "^[A-Z]{3}$"
previous_valueRequired

string

Finite numeric amount encoded as text; preserve decimal representation.

  • Maximum characters: 1024
  • Pattern: "^ *[+-]?(?:[0-9]+(?:\\.[0-9]*)?|\\.[0-9]+)(?:[eE][+-]?[0-9]+)? *$"
current_valueRequired

string

Finite numeric amount encoded as text; preserve decimal representation.

  • Maximum characters: 1024
  • Pattern: "^ *[+-]?(?:[0-9]+(?:\\.[0-9]*)?|\\.[0-9]+)(?:[eE][+-]?[0-9]+)? *$"
tierRequired

null

methodRequired

string

  • Value: "derived"
confidenceRequired

null

revisionRequired

Generation

SHA-256 of the published release generation.

  • Pattern: "^[a-f0-9]{64}$"
basisRequired

string

  • Value: "monthly-declared-cn8-v1"
ReleaseDiffobject | object | object | object | object

object | object | object | object | object

Derived comparison of published monthly CN8 declarations. revision is the generation hash, not an integer. tier and confidence are null rather than inferred source scores.

Exactly one of

NewOperatorDiff

  • Unknown properties are refused.

OperatorReturnedDiff

  • Unknown properties are refused.

NewOperatorCommodityDiff

  • Unknown properties are refused.

NewPartnerForCommodityDiff

  • Unknown properties are refused.

CommodityValueChangeDiff

  • Unknown properties are refused.
ExportJobobject

object

Private to the creating API key and organisation. cap is the minimum of row_limit, the organisation allowance and 100000. download_url is non-null only for completed jobs; the property is always returned. Files expire 24 hours after creation; queue deadline is 30 minutes.

  • Unknown properties are refused.
PropertyPresenceType and constraints
idRequired

string

  • Format: "uuid"
statusRequired

string

  • Allowed: "pending", "running", "completed", "failed", "expired"
formatRequired

string

  • Allowed: "csv", "parquet"
endpointRequired

string

  • Pattern: "^/(?:reporters|releases|operators|flows|partners|diffs|operators/hmrc_uktradeinfo/[0-9]{1,12}/links)$"
capRequired

integer

  • Minimum: 1
  • Maximum: 100000
rowsRequired

integer

  • Minimum: 0
  • Maximum: 100000
bytesRequired

integer

  • Minimum: 0
  • Maximum: 268435456
truncatedRequired

boolean

True when further rows existed after the cap; false for a complete result, including an empty one.

created_atRequired

Instant

  • Format: "date-time"
expires_atRequired

Instant

  • Format: "date-time"
finished_atRequired

string | null

Any of

Instant

  • Format: "date-time"

null

error_codeRequired

string | null

Any of

string

  • Allowed: "invalid_request", "publication_changed", "api_unavailable", "export_expired", "export_access_denied", "export_too_large", "export_failed", "storage_unavailable"

null

status_urlRequired

string

  • Pattern: "^/v1/exports/[a-f0-9-]{36}$"
download_urlRequired

string | null

Any of

string

  • Pattern: "^/v1/exports/[a-f0-9-]{36}/download$"

null

ReportersResponseobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
dataRequired

array<object>

Array items

ReporterRecord

  • Unknown properties are refused.
metaRequired

CountMeta

  • Unknown properties are refused.
ReleasesResponseobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
dataRequired

array<object>

  • Maximum items: 500
Array items

ReleaseRecord

  • Unknown properties are refused.
metaRequired

PageMeta

  • Unknown properties are refused.
OperatorsResponseobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
dataRequired

array<object>

  • Maximum items: 500
Array items

OperatorSearchRecord

  • Unknown properties are refused.
metaRequired

PublishedPageMeta

  • Unknown properties are refused.
OperatorResponseobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
dataRequired

OperatorProfile

Declared directory attributes from attributes_period. No inferred registry match, company turnover or shipment values.

  • Unknown properties are refused.
metaRequired

PublishedMeta

  • Unknown properties are refused.
LinksResponseobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
dataRequired

array<object>

  • Maximum items: 500
Array items

OperatorLink

  • Unknown properties are refused.
metaRequired

PublishedPageMeta

  • Unknown properties are refused.
FlowsResponseobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
dataRequired

array<object>

  • Maximum items: 500
Array items

TradeFlow

One published source cell. Amount is in currency; mass is kilograms. Null is not zero. All measures are null for suppressed cells; non-suppressed value is a finite number. Negative adjustments and duplicate cells are preserved.

  • Unknown properties are refused.
metaRequired

FlowMeta

  • Unknown properties are refused.
CommodityResponseobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
dataRequired

Commodity

Loaded nomenclature entry independent of trade activity. Parent and residual codes remain verbatim; a parent is not implicitly an HS6. hs6 is null when no unique mapping exists, except a loaded HS6 entry identifies itself. Validity boundaries are inclusive; null means an open boundary.

  • Unknown properties are refused.
metaRequired

ReferenceMeta

  • Unknown properties are refused.
PartnersResponseobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
dataRequired

array<object>

  • Maximum items: 500
Array items

Partner

A partner code present in the selected month, enriched only by the effective loaded mapping. Unmapped and residual codes remain present with null labels or ISO codes. Null validity boundaries are open.

  • Unknown properties are refused.
metaRequired

PartnerMeta

  • Unknown properties are refused.
DiffsResponseobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
dataRequired

array<object | object | object | object | object>

  • Maximum items: 500
Array items

ReleaseDiff

Derived comparison of published monthly CN8 declarations. revision is the generation hash, not an integer. tier and confidence are null rather than inferred source scores.

metaRequired

DiffMeta

  • Unknown properties are refused.
ExportResponseobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
dataRequired

ExportJob

Private to the creating API key and organisation. cap is the minimum of row_limit, the organisation allowance and 100000. download_url is non-null only for completed jobs; the property is always returned. Files expire 24 hours after creation; queue deadline is 30 minutes.

  • Unknown properties are refused.
metaRequired

PublishedMeta

  • Unknown properties are refused.
Errorobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
errorRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
codeRequired

string

  • Allowed: "invalid_request", "invalid_cursor", "invalid_api_key", "api_access_denied", "scope_denied", "market_denied", "diffs_denied", "not_found", "method_not_allowed", "publication_changed", "export_limit", "export_unavailable", "export_expired", "export_access_denied", "export_too_large", "unsupported_media_type", "payload_too_large", "api_quota_exhausted", "api_rate_limited", "api_unavailable"
messageRequired

string

request_idRequired

string

  • Format: "uuid"
ReportersExportRequestobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
endpointRequired

string

  • Value: "/reporters"
paramsRequired

object

  • Unknown properties are refused.
formatRequired

string

  • Allowed: "csv", "parquet"
row_limitOptional

integer

  • Minimum: 1
  • Maximum: 100000
  • Default: 100000
ReleasesExportRequestobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
endpointRequired

string

  • Value: "/releases"
paramsRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
reporterOptional

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
formatRequired

string

  • Allowed: "csv", "parquet"
row_limitOptional

integer

  • Minimum: 1
  • Maximum: 100000
  • Default: 100000
OperatorsExportRequestobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
endpointRequired

string

  • Value: "/operators"
paramsRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
qRequired

string

  • Minimum characters: 2
  • Maximum characters: 80
reporterOptional

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
formatRequired

string

  • Allowed: "csv", "parquet"
row_limitOptional

integer

  • Minimum: 1
  • Maximum: 100000
  • Default: 100000
LinksExportRequestobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
endpointRequired

string

  • Pattern: "^/operators/hmrc_uktradeinfo/[0-9]{1,12}/links$"
paramsRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
fromOptional

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
toOptional

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
formatRequired

string

  • Allowed: "csv", "parquet"
row_limitOptional

integer

  • Minimum: 1
  • Maximum: 100000
  • Default: 100000
FlowsExportRequestobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
endpointRequired

string

  • Value: "/flows"
paramsRequired

object

  • Unknown properties are refused.
  • When partner_scheme is provided, also provide: partner.
PropertyPresenceType and constraints
reporterOptional

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
commodityOptional

CommodityCode

CN8: eight digits; HS6: six digits; HS2: two digits, optionally followed by six hyphens. Codes are never converted implicitly.

  • Pattern: "^(?:[0-9]{8}|[0-9]{6}|[0-9]{2}(?:------)?)$"
commodity_schemeOptional

CommodityScheme

  • Default: "CN8"
  • Allowed: "CN8", "HS6", "HS2"
partnerOptional

GeoCode

Original source code, including residual or aggregate codes. Does not imply an ISO identity.

  • Pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$"
partner_schemeOptional

GeoScheme

  • Pattern: "^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$"
flowOptional

Flow

  • Allowed: "import", "export"
fromOptional

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
toOptional

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"

All of

JSON

Conditional validation rule
{
  "if": {
    "required": [
      "commodity",
      "commodity_scheme"
    ],
    "properties": {
      "commodity_scheme": {
        "const": "CN8"
      }
    }
  },
  "then": {
    "properties": {
      "commodity": {
        "type": "string",
        "pattern": "^[0-9]{8}$"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "required": [
      "commodity",
      "commodity_scheme"
    ],
    "properties": {
      "commodity_scheme": {
        "const": "HS6"
      }
    }
  },
  "then": {
    "properties": {
      "commodity": {
        "type": "string",
        "pattern": "^[0-9]{6}$"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "required": [
      "commodity",
      "commodity_scheme"
    ],
    "properties": {
      "commodity_scheme": {
        "const": "HS2"
      }
    }
  },
  "then": {
    "properties": {
      "commodity": {
        "type": "string",
        "pattern": "^[0-9]{2}(?:------)?$"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "required": [
      "commodity"
    ],
    "not": {
      "required": [
        "commodity_scheme"
      ]
    }
  },
  "then": {
    "properties": {
      "commodity": {
        "type": "string",
        "pattern": "^[0-9]{8}$"
      }
    }
  }
}

JSON

Conditional validation rule
{
  "if": {
    "required": [
      "partner"
    ],
    "not": {
      "required": [
        "partner_scheme"
      ]
    }
  },
  "then": {
    "properties": {
      "partner": {
        "type": "string",
        "pattern": "^[A-Z]{2}$"
      }
    }
  }
}
formatRequired

string

  • Allowed: "csv", "parquet"
row_limitOptional

integer

  • Minimum: 1
  • Maximum: 100000
  • Default: 100000
PartnersExportRequestobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
endpointRequired

string

  • Value: "/partners"
paramsRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
reporterOptional

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
periodOptional

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
formatRequired

string

  • Allowed: "csv", "parquet"
row_limitOptional

integer

  • Minimum: 1
  • Maximum: 100000
  • Default: 100000
DiffsExportRequestobject

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
endpointRequired

string

  • Value: "/diffs"
paramsRequired

object

  • Unknown properties are refused.
PropertyPresenceType and constraints
reporterOptional

Reporter

ISO 3166-1 alpha-2 reporter. GB is the currently published market.

  • Pattern: "^[A-Z]{2}$"
periodOptional

Period

  • Pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])$"
kindOptional

DiffKind

  • Allowed: "new_operator", "operator_returned", "new_operator_commodity", "new_partner_for_commodity", "commodity_value_change"
formatRequired

string

  • Allowed: "csv", "parquet"
row_limitOptional

integer

  • Minimum: 1
  • Maximum: 100000
  • Default: 100000
ExportRequestobject | object | object | object | object | object | object

object | object | object | object | object | object | object

Exactly one of

ReportersExportRequest

  • Unknown properties are refused.

ReleasesExportRequest

  • Unknown properties are refused.

OperatorsExportRequest

  • Unknown properties are refused.

LinksExportRequest

  • Unknown properties are refused.

FlowsExportRequest

  • Unknown properties are refused.

PartnersExportRequest

  • Unknown properties are refused.

DiffsExportRequest

  • Unknown properties are refused.