# hkid-quota-monitor: A 2-Minute Watchdog for Hong Kong ID Card Booking Slots

> This open-source Python project monitors the Hong Kong Immigration Department's smart ID card appointment quotas, sends email and Feishu alerts when slots open, and is explicitly a third-party tool, not an official service.

**chen1111-a/hkid-quota-monitor** — A monitoring dashboard for Hong Kong Immigration Department smart ID card appointment quotas: checks every 5 minutes with email/Feishu notifications when slots open (third-party tool, not official).

- Repository: https://github.com/chen1111-a/hkid-quota-monitor
- Stars: 47 · Forks: 11
- Language: Python
- License: not declared
- Published: 2026-08-22 · Updated: 2026-08-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/chen1111-a-hkid-quota-monitor

## What This Monitor Actually Solves

The project's design assumes you are in mainland China, where direct access to the booking site may be unreliable. The dashboard is hosted on pages.dev and github.io, but the notification chain goes through domestic email and Feishu, which the README says works without a VPN. This is a niche but real problem: many Hong Kong ID card applicants live or work across the border, and their network path to the official site is not always stable.

## How the Data Flow Works

There is also a functions/ directory that the README says handles /data/* requests as an edge proxy back to GitHub with a 30-second cache, and /api/runs for audit. This means the dashboard does not depend on the build frequency of Cloudflare Pages, which is a smart separation. The data is committed to the repository, so every change is a Git commit, which gives you a history of quota changes over time. That is a useful side effect, though the README does not claim any analysis of that history.

## Deployment: Six Steps to Your Own Instance

If you do not configure cron-job.org, the workflow falls back to a 15-minute schedule. The README points to docs/cron-setup.md for the two-minute setup. For the subscription panel to work, you must edit three constants in index.html: OWNER_REPO, SUBSCRIBE_EMAIL, and FEISHU_GROUP_URL. If you do not change OWNER_REPO, the subscription entry hides automatically, which prevents a fork from accidentally sending subscription emails to the original author. That is a thoughtful guard against a common fork mistake.

## Subscription Parsing and Its Quirks

The parser is not a full natural language engine. It recognizes a fixed set of office names and date patterns. If you write a date in an unsupported format, the README says the line becomes invalid and will not fire, which is a silent failure. The confirmation email echoes the parsed scope, so you can catch mistakes, but only if you read it carefully. The system does not support arbitrary query syntax beyond what the README documents.

## Notification Tiers and Throttling

The throttling mechanism is the most important part. The README mentions that the official API has load-balanced data jitter, and a naive diff would fire alerts every cycle. The notification layer has a per-cell cooldown, so a slot that fluctuates between 304 and 346 within a minute will not spam you. This is a practical engineering decision that shows the author understood the data source's instability. Without it, the tool would be unusable.

## Cloudflare Pages as a Second Entry Point

The README recommends deploying the same repository to Cloudflare Pages as a backup entry, because github.io can be unreliable for mainland users. The setup is simple: connect the repo, leave build settings empty, and deploy. The critical step is to exclude data/* from build watch paths, otherwise the free tier's 500 builds per month will be exhausted in a day, since the data directory updates every few minutes. This is a concrete cost trap that the README explicitly warns about. The functions/ directory then serves /data/* as an edge proxy with a 30-second cache, which means the dashboard does not depend on the build frequency. It also proxies /api/runs for scheduling audits, so you can see the green check marks even from the mainland. This dual-entry design is a realistic answer to the network fragmentation between mainland and Hong Kong.

## Limitations and the Wrong Tool Cases

The tool also depends on external services: cron-job.org for the trigger, GitHub Actions for execution, and jsDelivr for cache refresh. If any of these is down or rate-limited, monitoring stops. The README does not mention any fallback beyond the 15-minute schedule, which is still a dependency. For a tool that promises two-minute detection, this is a fragility that you should accept only if you are not in a life-critical situation. The project is also not a general-purpose scraper; it is hardcoded to the Hong Kong ID card quota API, so it has no value outside that narrow use case.

## Alternatives and How They Differ

If you want a more robust notification system, you could build your own scheduler with a VPS and cron, but that adds cost and maintenance. This project's zero-server, zero-cost approach is appealing, but it trades off reliability for convenience.

## Maintenance and License Considerations

Maintenance cost is low if you deploy it yourself. The main ongoing tasks are updating config.json thresholds, monitoring the email sending limits, and watching for changes in the official API structure. The README links to docs/api-notes.md for the interface structure, so you have a starting point for debugging if the API changes. The project has no release tags, so there is no versioned upgrade path; you would have to pull from the default branch and hope nothing breaks. That is a typical limitation of a small, single-author tool.

## Conclusion

Adopt hkid-quota-monitor if you need a free, self-hostable way to watch Hong Kong ID card appointment slots and get alerts without manual refreshing. Do not use it if you expect guaranteed booking success, since it only monitors and never books. Before relying on it, verify the quota API endpoint still works, confirm your email provider's daily sending limits, and test the Fernet key generation. The project is a practical, low-cost tool, but its notification delivery depends on third-party services like cron-job.org and GitHub Actions, so it is not a replacement for official channels.

## FAQ

### How often does hkid-quota-monitor check for HKID appointment slots?

About every two minutes, driven by a cron-job.org job that triggers a GitHub Actions workflow running python -m quota_monitor.run. Without the two-minute cron configured, the workflow falls back to a 15-minute schedule.

### Does hkid-quota-monitor book appointments automatically?

No. It is a third-party monitoring and notification tool only, and it states explicitly that it does nothing of the kind. Data comes from the public quota endpoint of the Immigration Department page, polled less often than that page refreshes itself.

### How do I stop hkid-quota-monitor from alerting me about dates I do not want?

Set monitor_before in config.json. Slots dated after that line are neither pushed nor highlighted, and the author measures that late-dated slots are around three tenths of everything released, so it is mostly noise.

### Why do hkid-quota-monitor alerts not fire every polling round?

The official endpoint is behind load balancing and was measured fluctuating by about forty slots for the same office within one minute. The notification layer keeps a per-cell cooldown so a flickering office and date cannot alert repeatedly.

### What does it take to run my own copy of hkid-quota-monitor?

Fork the repository, enable the workflow in your fork's Actions tab since GitHub disables fork workflows by default, then set Pages to the main branch root. Notifications need five repository secrets including a Fernet SUBSCRIBER_KEY, and the only Python dependency is cryptography>=42.

## Sources

- [Official README](https://github.com/chen1111-a/hkid-quota-monitor#readme)
- [Project repository](https://github.com/chen1111-a/hkid-quota-monitor)
- [README](https://github.com/chen1111-a/hkid-quota-monitor/blob/main/README.md)
- [Releases](https://github.com/chen1111-a/hkid-quota-monitor/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chen1111-a-hkid-quota-monitor