DEV Community

Russell Yapp
Russell Yapp

Posted on

Find UK importers of one HS code with an Apify Actor

You sell something, or you research a market, and you want a list of UK companies that bring one product in. HMRC publishes monthly lists of UK importers and exporters, but they are large files keyed by commodity code. This is a how-to for pulling out one code.

I publish the UK Importers and Exporters: HMRC Trade Data Actor. The data is HMRC UK Trade Info, published under the Open Government Licence v3.0.

Step 1: find the code (free)

If you do not know the HS code, hsSuggest mode turns keywords into suggested codes. It reads no trader data, so nothing is charged.

{ "mode": "hsSuggest", "hsKeywords": ["heat pump"] }
Enter fullscreen mode Exit fullscreen mode

Each keyword gets one row. A matches row lists up to 10 suggestions with the code, its level, a description and a score. Matching is plain word matching, with plurals folded and no synonyms, so "tyre" will not find "tire". Check each suggestion against the UK Trade Tariff before you rely on it.

Step 2: search for the traders

{
  "mode": "search",
  "hsCodes": ["8419"],
  "flows": ["imports"],
  "maxItems": 200
}
Enter fullscreen mode Exit fullscreen mode

A code can have 2, 4, 6 or 8 digits and matches every 8-digit code that starts with it. With no months given, the search reads the latest month HMRC has published. For a range, give monthFrom and monthTo as YYYY-MM, both or neither, at most 12 months per run.

To keep one region, add postcodeDistricts, for example ["M", "SK", "WA1"]. A district matches exactly (M1 matches M1, not M11), and an area of letters such as M matches M1 and M60, not ME1. A full postcode is refused.

What a row holds

One row per trader, flow and month: name, postcodeDistrict, flow, month, and the codes that matched in cn8Codes, hs6Codes and hs4Codes. There is no address field, and only the outward part of the postcode is given.

What it costs

On the Free plan, as shown on the Actor's page on 19 November 2026, a row costs $0.002, and a run costs $0.005 once it has read trader data. Bronze, Silver and Gold plans pay less per trader. The README's own examples are a 20-row search at $0.045 and a 1,000-row search at $2.005. At 200 rows, the run above costs at most 200 x $0.002 + $0.005 = $0.405.

The run fee is charged even if no row comes back, but a refused input charges nothing. maxItems goes up to 100,000, and Apify's maximum-charge setting caps a run too.

What to keep in mind

  • Sole traders are people. Names that are not clearly an organisation's are left out. A name needs a marker such as Limited, Ltd, PLC or LLP to be returned, and the ones left out are counted in RUN_SUMMARY.withheldPersons.
  • The data is about five weeks behind. July 2026 was published on 7 September 2026. A month not yet published is listed in RUN_SUMMARY.notPublished.
  • Older months have limits. A search makes at most 60 queries across older months, codes and flows. A wider one is refused before anything is read, and nothing is charged.
  • A row shows only matched codes. In search, each row lists the codes that matched, not everything the trader dealt in. Lookup mode lists every code for a named company.
  • HMRC's removals apply. HMRC removes a trader who asks from the following month's publication, and the Actor follows the current publication. The README says how to ask us to remove a trader.

Want to be told about new traders instead? alert mode records the first month it reads, sends no rows that time, and then sends traders new to your codes as each month is published. The README's example is a monthly alert that finds 30 new traders, costing $0.065.

Contains public sector information licensed under the Open Government Licence v3.0 (HMRC, UK Trade Info). This Actor is not affiliated with HMRC.

The Actor: https://apify.com/yappman/uk-importers-exporters

Top comments (0)