# Hong Kong Trade Statistics API (C\&SD) (`bigdws77/hk-trade-pulse`) Actor

Get Hong Kong's official monthly trade data (C\&SD): imports, exports and re-exports by country and SITC product group, with year-on-year change. Track HK trade with China, the US and more. Export to CSV, Excel or JSON.

- **URL**: https://apify.com/bigdws77/hk-trade-pulse.md
- **Developed by:** [Pulse Data](https://apify.com/bigdws77) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Hong Kong Trade Statistics API (C\&SD) — HK Trade Pulse

Get Hong Kong's official external merchandise trade figures — imports, domestic exports, re-exports, total exports and total trade — as clean, analysis-ready rows. Break them down by country/territory and by SITC commodity group, with year-on-year change calculated for you.

Data comes from the Census and Statistics Department's (C\&SD) Trade-IDDS API, published on DATA.GOV.HK. No scraping, no logins, no personal data.

### What you get

One row per period × trade type × country × commodity:

| Field | Example |
|---|---|
| `period` | `202608` |
| `tradeType` | `Total Exports` |
| `countryCode` / `country` | `CN` / `CHINESE MAINLAND` |
| `commodityCode` / `commodity` | `77` / `ELECTRICAL MACHINERY…` |
| `valueHkdThousands` | `352599371` |
| `valueYearAgoHkdThousands` | value for the same period a year earlier |
| `yoyChangePct` | year-on-year change in % |
| `source` | attribution line |

Export as JSON, CSV, Excel, or pull it through the Apify API.

### Typical uses

- Monthly tracking of Hong Kong exports to a given market (e.g. US, Chinese Mainland, ASEAN members).
- Watching a product group — semiconductors (SITC 776), telecoms equipment (SITC 76), electrical machinery (SITC 77).
- Feeding dashboards, research notes or AI agents with the latest official figures on a schedule.

### Input

- **Trade types** — any of imports, domestic exports, re-exports, total exports, total trade.
- **Frequency** — monthly (default) or annual.
- **Months back** — defaults to the last 12 published months. Or set a start/end period.
- **Countries** — C\&SD two-letter codes (e.g. `CN`, `US`, `JP`), or `ALL`. Empty = Hong Kong totals.
- **Commodity breakdown** — none, or SITC 1-, 2- or 3-digit codes.
- **Year-on-year** — on by default.

### FAQ

**Is it free?** Yes. The Actor itself is free; you only pay Apify's platform usage, which for a typical run is a fraction of a cent.

**How current is the data?** C\&SD publishes each month's figures roughly four to six weeks after the month ends. The Actor checks which month is the latest published and uses it automatically, so a scheduled run always picks up the newest data.

**Which country codes should I use?** C\&SD's two-letter codes, e.g. `CN` for the Chinese Mainland and `US` for the United States. Leave the field empty for Hong Kong totals, or use `ALL` for every trading partner.

**What is SITC?** The UN's Standard International Trade Classification. One digit is a section (`7` = machinery and transport equipment), two digits a division (`77` = electrical machinery), three digits a group (`776` = semiconductors and integrated circuits).

**Can I run it every month automatically?** Yes. Create a schedule in Apify (e.g. the 10th of each month) and connect the output to Google Sheets, a webhook, Make, Zapier or your own API client.

**Can an AI agent use it?** Yes. It works through the Apify API and Apify's MCP server, so assistants and agents can call it with plain inputs like "total exports to the US, last 12 months".

**Are the values adjusted?** No. They are the published HK$ thousand values at current prices, including C\&SD's later revisions if you re-run for an earlier period.

### Notes

- Values are in HK$ thousands, as published. C\&SD publishes monthly figures with a lag of about a month; the Actor finds the latest published month automatically.
- Figures are as published by C\&SD and may be revised by them later. Read C\&SD's footnotes for definitions (e.g. re-exports, country of consignment).
- This Actor is not affiliated with or endorsed by the HKSAR Government.

### Source and licence

Source: Census and Statistics Department, HKSAR Government — Interactive Data Dissemination Service for Trade Statistics (Trade-IDDS), via DATA.GOV.HK. C\&SD states these statistics are free for commercial and non-commercial use, subject to its Intellectual Property Rights Notice. Every output row carries this attribution.

# Actor input Schema

## `tradeTypes` (type: `array`):

Which trade flows to return.

## `frequency` (type: `string`):

Monthly figures, or annual year-to-date totals.

## `monthsBack` (type: `integer`):

Number of months ending at the latest published month. Ignored if start period is set.

## `startPeriod` (type: `string`):

YYYYMM for monthly, YYYY for annual. Leave empty for automatic.

## `endPeriod` (type: `string`):

YYYYMM for monthly, YYYY for annual. Leave empty for the latest published.

## `countries` (type: `array`):

Two-letter codes as used by C\&SD, e.g. CN (Chinese Mainland), US, JP. Use ALL for every country. Leave empty for Hong Kong totals.

## `commodityLevel` (type: `string`):

Optionally break results down by SITC commodity group.

## `commodityCodes` (type: `array`):

Required when a breakdown is chosen, e.g. 7 (machinery), 77 (electrical machinery), 776 (semiconductors).

## `compareYearOnYear` (type: `boolean`):

Also fetches the same period a year earlier and adds valueYearAgo and yoyChangePct.

## Actor input object example

```json
{
  "tradeTypes": [
    "total_exports",
    "imports"
  ],
  "frequency": "monthly",
  "monthsBack": 12,
  "countries": [
    "CN",
    "US"
  ],
  "commodityLevel": "none",
  "compareYearOnYear": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "countries": [
        "CN",
        "US"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("bigdws77/hk-trade-pulse").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "countries": [
        "CN",
        "US",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("bigdws77/hk-trade-pulse").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "countries": [
    "CN",
    "US"
  ]
}' |
apify call bigdws77/hk-trade-pulse --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bigdws77/hk-trade-pulse"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/rBrbvFaCmdZ4zhYpl/builds/eiUagthf3BxWpryIZ/openapi.json