README.md

Microsoft Clarity API

Version: 0.0.3

Microsoft Clarity Data Export API

This Python library allows you to work with the dashboard data. The data can be structured over a specified date range and can break down insights by up to three dimensions.

Find out more about the Clarity Data Export API

This repository is actively maintained - Contributions are welcome!

Getting Started:

Prerequisites

• An active Microsoft Clarity account. Learn how to sign up for Clarity.
• An API access token generated by the project's admin from the settings page.
• Python3.8+

Obtaining Access Tokens

Note: Only project admins can manage access tokens.

1. Go to your Clarity project. Select Settings -> Data Export -> Generate new API token.
2. Provide a descriptive name for the token for easy identification.

Parameters

• numOfDays: (1, 2, or 3) The number of days for the data export since the API call, relating to the last 24, 48, or 72 hours, respectively.
• dimension1: The first dimension to break down insights.
• dimension2: The second dimension to break down insights.
• dimension3: The third dimension to break down insights.

Dimension Options:

• Browser
• Device
• Country
• OS
• Source
• Medium
• Campaign
• Channel
• URL

Usage:

#!/usr/bin/python
# coding: utf-8
import clarity_api

# Use token generated from the steps above
token = "<TOKEN>"
url = "https://www.clarity.ms"
client = clarity_api.Api(url=url, token=token)

data = client.get_data_export(number_of_days=2, dimension_1="OS", dimension_2="Channel")
print("Pydantic Object:", data)
print("Raw Request Output:", data.raw_output)
print("JSON Request Output:", data.json_output)
print("Pydantic Object Model Dump:", data.model_dump())
print("Request Status Code:", data.status_code)
print("Request Error:", data.error)

Installation Instructions:

Install Python Package

python -m pip install clarity-api

Tests:

pre-commit check

pre-commit run --all-files

pytest

pytest ./test/test_clarity_models.py

Repository Owners: