Visitor Badge

Docs

How to use?

Markdown


                ![visitors](https://visitor-badge.example.net/badge?page_id=page.id&left_color=red&right_color=green)

HTML


                <img src="https://visitor-badge.example.net/badge?page_id=page.id&left_color=red&right_color=green" />

API


                    curl -X GET "http://visitor-badge.example.net/count?page_id=page.id" 

                    // output: {"value": 100}

Unique Visitor API


                    curl -X GET "http://visitor-badge.example.net/count?page_id=page.id&unique=true" 

                    // output: {"value": 42, "method": "fingerprint"}

Options

Params	Required	Default	Description
page_id	Required	null	Unique string to best represent your page
namespace	Optional	default	Unique key to group all your pages and avoid conflict with others (max 10 chars)
read	Optional	false	Only return existing count, don't increment
unique	Optional	false	Only count unique visitors within a given window. Uses cookie-based dedup with server-side fingerprint fallback for cross-origin embeds
timeframe	Optional	600	Time window (seconds) for unique visitor dedup. Range: 60-86400 (1 min to 24 hrs)
*left_color	Optional	#595959	Left side color of the badge
*left_text	Optional	visitor	Left side text of the badge
*right_color	Optional	#1283c3	Right side color of the badge

Note: * options only applied for path /badge

Bot Filtering

Common bots (Googlebot, bingbot, crawlers, etc.) are automatically detected and excluded from visitor counts.

Public Servers:

URL: https://visitor-badge.one9x.com
Free: Yes

Please be aware that this server is hosted on a homelab environment, which may result in occasional downtime or data loss. To minimize the risk of data loss, automated hourly backups are taken with 48-hour hourly retention and 30-day daily retention.

Admin API

Manage namespace-level configuration. Requires X-API-Key header. Rate limited to 10 req/min per IP.

List Namespaces


                    curl -H "X-API-Key: YOUR_KEY" http://localhost:5000/admin/namespaces

Set Namespace Defaults


                    curl -X PUT -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \

                      -d '{"badge_defaults": {"left_color": "blue", "left_text": "hits"}}' \

                      http://localhost:5000/admin/namespace/myns

Health Check


                    curl http://localhost:5000/health/backup 

                    // output: {"status": "healthy", "last_backup": "2026-03-29T12:00:00Z"}

Count visitors for your GitHub, Blog or Portfolio Site