{
  "openapi": "3.0.1",
  "info": {
    "title": "UK Importers and Exporters: HMRC Trade Data",
    "description": "Find UK businesses that imported or exported goods by HS code and month, look companies up, and get alerts on traders new to a commodity. HMRC UK Trade Info data under the OGL. Names that are not clearly an organisation's are left out. Not affiliated with HMRC.",
    "version": "0.1",
    "x-build-id": "CJ94kyDd2bXqD330F"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/yappman~uk-importers-exporters/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-yappman-uk-importers-exporters",
        "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/yappman~uk-importers-exporters/runs": {
      "post": {
        "operationId": "runs-sync-yappman-uk-importers-exporters",
        "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/yappman~uk-importers-exporters/run-sync": {
      "post": {
        "operationId": "run-sync-yappman-uk-importers-exporters",
        "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",
        "required": [
          "mode"
        ],
        "properties": {
          "mode": {
            "title": "Mode",
            "enum": [
              "search",
              "lookup",
              "alert",
              "hsSuggest"
            ],
            "type": "string",
            "description": "Which job to run (default 'search'). 'search': traders of hsCodes in one month or up to 12. 'lookup': what named companies traded. 'alert': traders new to your hsCodes each month HMRC publishes. 'hsSuggest': suggested HS codes for keywords; free, reads no trader data. Other modes charge run ($0.005 on every plan) once trader data is read, plus trader per row ($0.002 on the Free plan, less on higher plans).",
            "default": "search"
          },
          "hsCodes": {
            "title": "HS codes (search, alert)",
            "maxItems": 20,
            "type": "array",
            "description": "Required in search and alert; not used by lookup or hsSuggest. 1 to 20 codes of 2, 4, 6 or 8 digits only (HS chapter, heading, subheading or CN8), such as 8419; a code matches every 8-digit code that starts with it. No default (the Console form prefills 8419). Not sure of a code? Run hsSuggest first. An alert's codes are fixed for its alertId.",
            "items": {
              "type": "string"
            }
          },
          "hsKeywords": {
            "title": "Keywords (hsSuggest)",
            "maxItems": 5,
            "type": "array",
            "description": "Required in hsSuggest; not used by other modes. 1 to 5 words or short phrases, such as heat pump: each 3 to 60 characters of A-Z, a-z, 0-9, spaces and hyphens, with at least one letter (a code here is refused: use hsCodes). Each gives one row with up to 10 suggested codes, or noMatch or tooVague, never a guess. Free: nothing is charged. Check a code against the UK Trade Tariff, then use it in hsCodes.",
            "items": {
              "type": "string"
            }
          },
          "postcodeDistricts": {
            "title": "Postcode districts (search, alert)",
            "maxItems": 20,
            "type": "array",
            "description": "Optional, search and alert only (refused in lookup and hsSuggest); default no filter. Up to 20 outward codes such as SW1A or M1, matched exactly, or letter-only areas such as SW or M (M matches M1 and M60, not ME1). Case and spaces ignored. A full postcode such as SW1A 1AA is refused: give SW1A. Organisations left out are counted in RUN_SUMMARY.filteredByPostcode; the price per row is unchanged. Fixed per alertId.",
            "items": {
              "type": "string"
            }
          },
          "companies": {
            "title": "Companies (lookup)",
            "maxItems": 20,
            "type": "array",
            "description": "Required in lookup; not used by other modes. 1 to 20 entries, each a company name or part of one (3 to 100 characters; matches any published name that contains it, up to 10 traders per name) or an HMRC trader id (digits). Names that are not clearly an organisation's are left out and counted in RUN_SUMMARY. Each row returned is charged as a trader ($0.002 on the Free plan, less on higher plans).",
            "items": {
              "type": "string"
            }
          },
          "flows": {
            "title": "Flows",
            "type": "array",
            "description": "Which trade directions to read: imports, exports or both (default both). Used by search, lookup and alert; not used by hsSuggest. Each row covers one flow and month, and each row is charged, so one flow returns and costs less. In a search with monthFrom and monthTo, months x hsCodes x flows must be at most 60.",
            "items": {
              "type": "string",
              "enum": [
                "imports",
                "exports"
              ],
              "enumTitles": [
                "Imports",
                "Exports"
              ]
            },
            "default": [
              "imports",
              "exports"
            ]
          },
          "monthFrom": {
            "title": "Month from",
            "type": "string",
            "description": "First month, YYYY-MM, from 2016-01; give monthTo too (both or neither), at most 12 months in all. Search and lookup only; refused in alert. Default when both are left out: search reads the latest month HMRC has published (about 5 weeks behind) and lookup the 12 months to it. In search, months x hsCodes x flows must be at most 60, or the input is refused and nothing is charged."
          },
          "monthTo": {
            "title": "Month to",
            "type": "string",
            "description": "Last month, YYYY-MM, given with monthFrom (both or neither) and not before it; at most 12 months in all, counting both ends. Search and lookup only; refused in alert. In search a month HMRC has not yet published is listed in RUN_SUMMARY.notPublished; lookup stops at the latest published month."
          },
          "alertId": {
            "title": "Alert id (alert)",
            "type": "string",
            "description": "Alert only, and required there. Your name for it, such as heat-exchangers: 1 to 40 characters of a-z, 0-9 and -, starting and ending with a letter or digit. No default. Its memory (hashes, not names) is in your own key-value store uk-traders-alert-<alertId>. Its hsCodes and postcodeDistricts are fixed: other codes need a new alertId. Its first run records the latest month, returns no rows and charges run ($0.005)."
          },
          "lookbackMonths": {
            "title": "Look-back months (alert)",
            "minimum": 1,
            "maximum": 24,
            "type": "integer",
            "description": "Alert only; not used by other modes. Whole number 1 to 24, default 12. A trader is sent, and charged as a trader row, when it has not traded your hsCodes in this many months before; it is sent again only if it comes back after that long.",
            "default": 12
          },
          "maxItems": {
            "title": "Maximum rows",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Hard cap on rows returned, and so on cost: each row is a trader event ($0.002 on the Free plan, less on higher plans), plus run ($0.005 on every plan) once trader data is read. Whole number 1 to 100,000; at most 5,000 in alert (the rest are sent next run). The Console form prefills 20 (up to $0.045 on the Free plan); through the API the default is 1,000 (up to $2.005). Not used by hsSuggest, which is free.",
            "default": 1000
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}