{
  "openapi": "3.0.1",
  "info": {
    "title": "UK Importers & Exporters by Product (HMRC Data)",
    "description": "Find UK companies that imported or exported a product each month, by HS code or keyword, from official HMRC trade data. New traders flagged; Companies House number, SIC code, status and size added; bulk-check your own company list. No API key; JSON via API or MCP, from $5 per 1,000 rows.",
    "version": "0.1",
    "x-build-id": "41QT0xWzzXV72Huaf"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/japan-open-data~uk-importer-exporter-directory/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-japan-open-data-uk-importer-exporter-directory",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/japan-open-data~uk-importer-exporter-directory/runs": {
      "post": {
        "operationId": "runs-sync-japan-open-data-uk-importer-exporter-directory",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/japan-open-data~uk-importer-exporter-directory/run-sync": {
      "post": {
        "operationId": "run-sync-japan-open-data-uk-importer-exporter-directory",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "hsCode": {
            "title": "HS / CN8 product code",
            "type": "string",
            "description": "The product, as a 2-, 4-, 6- or 8-digit HS / CN8 commodity code, e.g. \"8471\" (computers), \"610910\" (cotton T-shirts) or \"09011100\" (coffee beans). Up to 5 codes separated by commas. Look codes up on https://www.trade-tariff.service.gov.uk/. Ignored when \"productKeyword\" is set. Give either this or a product keyword.",
            "default": "8471"
          },
          "productKeyword": {
            "title": "Product keyword (instead of a code)",
            "type": "string",
            "description": "A product in plain English, e.g. \"coffee\", \"laptops\", \"solar panels\", \"bicycles\". It is turned into up to 5 HS codes (shown in every row as hsCode). Takes priority over \"hsCode\" when set."
          },
          "flow": {
            "title": "Imports or exports",
            "enum": [
              "import",
              "export"
            ],
            "type": "string",
            "description": "\"import\": companies that imported the product into the UK. \"export\": companies that exported it from the UK.",
            "default": "import"
          },
          "month": {
            "title": "Month",
            "type": "string",
            "description": "\"latest\" (default): the newest month HMRC has published (HMRC publishes about two months in arrears). Or a month such as \"2026-07\" (January 2016 or later).",
            "default": "latest"
          },
          "onlyNewTraders": {
            "title": "Only new traders",
            "type": "boolean",
            "description": "Only companies that traded this product this month but not in any of the previous months set by \"newTraderLookbackMonths\" (12 by default), i.e. isNewTrader = true. A monthly lead list of companies that have just started importing or exporting the product.",
            "default": false
          },
          "newTraderLookbackMonths": {
            "title": "New trader: months to look back",
            "minimum": 1,
            "maximum": 24,
            "type": "integer",
            "description": "A company is a new trader when it did not trade the same product code in the same direction in any of this many months before the chosen month. 12 (default) removes most seasonal importers; 1 compares with the previous month only. Each month costs one extra request to HMRC per code (about 1.2 seconds).",
            "default": 12
          },
          "postcodes": {
            "title": "Postcode areas or districts",
            "type": "array",
            "description": "Only companies in these UK postcode areas (letters, e.g. \"B\" = Birmingham, \"LS\" = Leeds) or districts (e.g. \"M1\", \"B62\"). Leave empty for the whole UK.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "companyName": {
            "title": "Company name contains",
            "type": "string",
            "description": "Only companies whose name contains this text at the start of a word, case ignored, e.g. \"Dell\". Leave empty for all."
          },
          "companies": {
            "title": "Bulk lookup: company names or numbers",
            "type": "array",
            "description": "Optional. A list of UK company names (e.g. \"Scan Computers International Ltd\") or Companies House company numbers (e.g. \"03174949\"), up to 1,000. When set, the Actor checks each one instead of searching by product: one row per company with its Companies House details and the CN8 codes it imported (or exported, see \"flow\") in \"month\". The product, postcode, company-name and new-trader filters and maxResults are ignored. Every company found among HMRC's traders is one charged row, even when it did not trade in that month (tradedInMonth: false); such a row is always a $0.005 company row, and only companies that traded in the month with a company number are $0.008 enriched company rows. Names that are not found, match several companies or are invalid give a free row; several entries for the same company share one row, charged once.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "addCompanyDetails": {
            "title": "Add Companies House details",
            "type": "boolean",
            "description": "Add the company number, status, type, incorporation date, accounts category (a size indicator) and SIC codes from Companies House to every company row, matched by company name and postcode (see companiesHouseMatch). A row with a company number is charged $0.008 (enriched company row) instead of $0.005. Always on for the bulk lookup, where companies with no trade in the month (tradedInMonth: false) stay $0.005 rows.",
            "default": true
          },
          "maxResults": {
            "title": "Maximum rows",
            "minimum": 1,
            "maximum": 50000,
            "type": "integer",
            "description": "Maximum number of company rows (each is charged). New traders come first, then the companies trading the most CN8 product lines, then A to Z; with several codes, the codes take turns.",
            "default": 20
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}