Google Analytics Badges


Node.js wrapper for a serverless service to generate Shields IO-style badges for Google Analytics. Authenticates with the Reporting API using JWT tokens and uses shields to generate badges for traffic stats. Fully customizable. Works with Universal Analytics but not GA4 properties.


Obtain service account credentials

Google service account credentials are needed for JWT authentication.

  1. Visit Google Cloud Platform > APIs & Services > Credentials or
  2. If you do not already have a project. Click Create project and give it a name. Refresh the page if changes aren't showing.
  3. With the project selected, add an API by clicking Dashboard > Enable APIs and services. Find the Google Analytics Reporting API and enable it.
  4. Select Create credentials > Service account, give the account a name. Click continue to skip through the optional steps.
  5. Click your newly created service account and scroll to the Keys section. Select Add key > Create new key > JSON, a file will be downloaded.

Your file will look like this. client_email and private_key are the values you'll need for the next steps.

	"type": "service_account",
	"project_id": "PROJECT_ID",
	"private_key_id": "PRIVATE_KEY_ID",
	"private_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY\n-----END PRIVATE KEY-----\n",
	"client_email": "CLIENT_EMAIL",
	"client_id": "CLIENT_ID",
	"auth_uri": "",
	"token_uri": "",
	"auth_provider_x509_cert_url": "",
	"client_x509_cert_url": "CLIENT_CERT_URL"

Add users to Analytics

To allow the service account access to your analytics data, you need to add it as a user. Full instructions can be found on Google's documentation. A summary of the steps is shown below.

  1. Sign in to Google Analytics. Click Admin > Account User Management.
  2. In the Account permissions list, click +, then click Add users.
  3. Enter the client_email for the service account. In the example file above, this would be
  4. Make sure the Read & Analyze permission is checked. Then click Add.

Now the setup is complete, time to deploy our serverless functions.


This Node.js project was built with serverless hosting in mind. However, it is also possible to integrate this into your current hosted projects.

Integrate into existing Node server

Adapt the code in integrate.js into your existing server code. Full documentation about the Core Reporting API can be found here.

Deploying a serverless instance

Since it requires private keys, the best way is to deploy your own instance of this service. We will be using Vercel for free serverless deployments.

Deploy with Vercel

Automate steps 1-5 with the button above

  1. Fork the project to your GitHub account.
  2. Create an account on Vercel.
  3. From the dashboard page click Import Project then specify the URL to your fork of the project on GitHub.
  4. Add the required environment variables CLIENT_EMAIL and PRIVATE_KEY. These values correspond to client-email and private-key above.
  5. Deploy and visit your application at <deploy-id> or the custom domain which you configured.

Visit your Google Analytics dashboard and obtain the viewId for your project of interest from Admin > View > View Settings > View ID. You can now generate badges for any of your Analytics projects with this endpoint.


Query Parameters

Param Description
viewId (Required) The View ID of your Google Analytics property
metric The metric id as specified in Google dev tools. Default: ga:users
startDate Start date for fetching Analytics data. Requests can specify a start date formatted as YYYY-MM-DD, or as a relative date (e.g., today, yesterday, or NdaysAgo where N is a positive integer). Default: 7daysAgo
endDate End date for fetching Analytics data. Requests can specify a start date formatted as YYYY-MM-DD, or as a relative date (e.g., today, yesterday, or NdaysAgo where N is a positive integer). Default: today
title Title for badge. Default: users
unit Unit of metric displayed on badge, e.g. 20k/week, 300/month. Special characters need to be URL encoded. Default: %2Fweek
color Color of shield. Default: green
style Shield style according to documentation. Default: plastic
si Whether to use SI abbreviations for numbers, e.g. 20k, 4M, 8B. Default: true


Using analytics data from my project Whisperify.

Default shield for users per week

In Markdown: ![Users](https://<deploy-id>

In HTML: <img src="https://<deploy-id>"/>

Users Shield

Pageviews per month


Views Shield

Bounce Rate over the past day with badge styles




Feel free to contribute corrections in this guide or provide documentation on how to set up this project on other serverless platforms such as GCP or AWS Lambda.



Connect with me:


Support and sponsor my work:

Send me your message

Trusted by

  • Duke University brand image
  • Emailio brand image
  • E.ON brand image
  • Kinetik Automotive brand image
  • Robert Ladkani brand image
  • SOD 64 brand image
  • Three11 brand image
  • dmarcian brand image
  • htmlBurger brand image
  • htmlBoutique brand image
  • 2create brand image