🍜 Umami Badges

Generate dynamic badges for your Umami website analytics! Show off your website traffic, page views, and visitor stats directly in your README files or on your website.

🚀 Quick Start

1. Get Your Website ID and API Key

You'll need:

• Your Website ID (found in your website settings)
• An API key (Account Settings → API keys)

⚠️ Security Notice: Your API key will be visible in the badge URL. This means anyone can view your website analytics data (views, visitors, etc.) but cannot modify settings or access other websites. Only use badges for public websites where you're comfortable sharing traffic statistics. You can rotate your API key anytime in Umami settings.

2. Generate Your Badge

Option A: Use the Web Interface

Visit: umami-badges.vercel.app

Option B: Build the URL yourself

Default (Umami Cloud):

https://umami-badges.vercel.app/api/{metric}?website={WEBSITE_ID}&token={API_TOKEN}&range=all&style=for-the-badge&cache=0

Self‑hosted or custom domain (add umamiUrl):

https://umami-badges.vercel.app/api/{metric}?website={WEBSITE_ID}&token={API_TOKEN}&range=all&style=for-the-badge&cache=0&umamiUrl={CUSTOM_UMAMI_API_URL}

3. Add to Your README

![Website Analytics](https://umami-badges.vercel.app/api/views?website=your-website-id&token=your-api-token&range=all&style=for-the-badge&cache=0)

📊 Available Metrics

Metric	Description	Example
views	Total page views
visitors	Unique visitors
visits	Total visits
bounce-rate	Bounce rate percentage
avg-session	Average session duration
live	Live visitors (last 30 minutes)

🎨 Customization Options

Parameter	Description	Values
range	Time range for stats	7d, 30d, 90d, all (default: all)
style	Badge style	flat, flat-square, for-the-badge, plastic, social
color	Badge color	brightgreen, green, blue, red, orange, yellow, purple, or hex codes
label	Custom label text	Any text (URL encoded)

🧪 Running Tests

To run the tests and view coverage:

1. Install the required dev dependency:

   npm install

2. Run the test coverage script:

   npm run test:coverage

This will execute the tests and generate a coverage report.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📣 Issues or Suggestions

Any issues or suggestions, please create an issue on Github.

☕ Buy me a coffee

Donations are welcome to appreciate my work and to keep this project alive, but isn't required at all.