### Quickstart OpenPanel Self-Hosting

Source: https://openpanel.dev/docs/self-hosting/self-hosting

This script clones the OpenPanel repository with the self-hosting branch, navigates to the self-hosting directory, and executes the setup script. After setup, it provides a command to start OpenPanel services.

```bash
git clone -b self-hosting https://github.com/Openpanel-dev/openpanel && cd openpanel/self-hosting && ./setup
# After setup is complete run `./start` to start OpenPanel
```

--------------------------------

### Manual Setup Steps for OpenPanel

Source: https://openpanel.dev/docs/self-hosting/self-hosting

Provides alternative manual steps if the `./setup` script fails. It involves installing Docker, Node.js, and npm, followed by running the 'npm run quiz' script within the self-hosting directory to configure the setup.

```bash
npm run quiz
```

--------------------------------

### Start OpenPanel Services

Source: https://openpanel.dev/docs/self-hosting/self-hosting

This script, located in the self-hosting folder, is used to start all the necessary OpenPanel services after the setup is complete. It ensures that your OpenPanel instance is running and accessible.

```bash
./start
```

--------------------------------

### Run OpenPanel Setup Script

Source: https://openpanel.dev/docs/self-hosting/self-hosting

This command navigates into the 'openpanel/self-hosting' directory and executes the 'setup' script. This script automates the installation of Node.js and Docker (if accepted) and then runs a node script to configure your OpenPanel setup based on your inputs.

```bash
cd openpanel/self-hosting
./setup
```

--------------------------------

### Clone OpenPanel Repository for Self-Hosting

Source: https://openpanel.dev/docs/self-hosting/self-hosting

This command clones the OpenPanel repository, specifically checking out the 'self-hosting' branch to ensure you have the correct version for self-hosting. It's the initial step before running any setup scripts.

```bash
git clone -b self-hosting https://github.com/Openpanel-dev/openpanel.git
```

--------------------------------

### OpenPanel Basic Operations Scripts

Source: https://openpanel.dev/docs/self-hosting/self-hosting

A set of essential bash scripts for managing the OpenPanel instance. Includes commands to start, stop, and view logs for all OpenPanel services. These scripts are run from the self-hosting directory.

```bash
./start    # Start all OpenPanel services
./stop     # Stop all OpenPanel services
./logs     # View real-time logs from all services
```

--------------------------------

### TypeScript: OpenPanel screenView Method Signature and Example

Source: https://openpanel.dev/docs/migration/beta-v1

Demonstrates the updated `screenView` method signature in TypeScript, which now accepts optional `properties` or a `path` string along with `properties`. It shows two examples of how to call the method, one with a path and properties, and another with just properties, defaulting the path to the current window location.

```typescript
screenView(properties?: TrackProperties): void;
screenView(path: string, properties?: TrackProperties): void;

// Example
op.screenView('/home', { title: 'Home' }); // path will be "/home"
op.screenView({ title: 'Home' }); // path will be what ever window.location.pathname is
```

--------------------------------

### Get Device & Technology Data - Example Request (Browser)

Source: https://openpanel.dev/docs/api/insights

Example cURL request to fetch browser data for a project within a specified date range. This demonstrates the use of the 'browser' endpoint and includes authentication headers.

```bash
curl 'https://api.openpanel.dev/insights/abc123/browser?range=7d' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

--------------------------------

### OpenPanel API Error Response Example

Source: https://openpanel.dev/docs/api/track

Example of an error response from the OpenPanel API. Errors are indicated by standard HTTP response codes, and the response body provides details about the error, such as an invalid client credential message.

```json
{
  "error": "Invalid client credentials",
  "status": 401
}
```

--------------------------------

### Install OpenPanel Next.js Dependencies

Source: https://openpanel.dev/docs/sdks/nextjs

Installs the necessary OpenPanel Next.js package using pnpm. This is the first step before initializing the SDK in your application.

```bash
pnpm install @openpanel/nextjs
```

--------------------------------

### Install OpenPanel SDK with npm

Source: https://openpanel.dev/docs/sdks/javascript

Install the OpenPanel SDK package using npm. This is the first step to using the SDK in your Node.js or generic Javascript project.

```bash
npm install @openpanel/sdk
```

--------------------------------

### Install OpenPanel Python SDK

Source: https://openpanel.dev/docs/sdks/python

Install the OpenPanel Python SDK using pip. This command downloads and installs the necessary package to enable tracking in your Python application.

```bash
pip install openpanel
```

--------------------------------

### Initialize OpenPanel Web SDK with NPM

Source: https://openpanel.dev/docs/sdks/script

Installs the OpenPanel Web SDK using NPM and initializes it with provided options. This is an alternative to the script tag method for integrating the SDK into your project.

```bash
npm install @openpanel/web
```

```javascript
import { OpenPanel } from '@openpanel/web';
 
const op = new OpenPanel({
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});
```

--------------------------------

### Install OpenPanel Web SDK via npm

Source: https://openpanel.dev/docs/sdks/web

Installs the OpenPanel Web SDK using npm. This is the first step to integrate OpenPanel tracking into your web application.

```bash
npm install @openpanel/web
```

--------------------------------

### Install React Native Dependencies

Source: https://openpanel.dev/docs/sdks/react-native

Installs the OpenPanel React Native SDK and its required peer dependencies, expo-application and expo-constants. Ensure these are installed to properly access device and app information.

```bash
npm install @openpanel/react-native
npx expo install expo-application expo-constants
```

--------------------------------

### Install OpenPanel Astro Dependencies

Source: https://openpanel.dev/docs/sdks/astro

Installs the necessary OpenPanel Astro package using pnpm. This is the first step to integrate OpenPanel into your Astro project.

```bash
pnpm install @openpanel/astro
```

--------------------------------

### Install OpenPanel Express Middleware

Source: https://openpanel.dev/docs/sdks/express

Install the OpenPanel Express middleware using pnpm. This is the first step to integrating OpenPanel with your Express application.

```bash
pnpm install @openpanel/express
```

--------------------------------

### Get Live Visitors with cURL

Source: https://openpanel.dev/docs/api/insights

Example of how to fetch the current number of active visitors on a website in real-time using cURL. Authentication is required via headers.

```bash
curl 'https://api.openpanel.dev/insights/abc123/live' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

--------------------------------

### Get UTM Campaign Data - Example Request

Source: https://openpanel.dev/docs/api/insights

Example cURL request to fetch UTM campaign source data for a given project ID. Includes the necessary API endpoint, date range parameter, and authentication headers (client ID and secret).

```bash
curl 'https://api.openpanel.dev/insights/abc123/utm_source?range=30d' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

--------------------------------

### OpenPanel Data Wipe Script

Source: https://openpanel.dev/docs/self-hosting/self-hosting

A critical bash script used for completely resetting your OpenPanel instance. It removes all containers, volumes, and associated data. Use this script with extreme caution only when intending to start fresh, as all data will be lost.

```bash
./danger_wipe_everything   # ⚠️ Removes all containers, volumes, and data
                           # Only use this if you want to start fresh!
```

--------------------------------

### Initialize OpenPanel SDK in TypeScript

Source: https://openpanel.dev/docs/self-hosting/self-hosting

This TypeScript code shows how to initialize the OpenPanel SDK. It imports the OpenPanel class and instantiates it with configuration options including the API URL, client ID, and various tracking settings.

```typescript
import { OpenPanel } from '@openpanel/sdk';
 
const op = new OpenPanel({
  apiUrl: 'https://your-domain.com/api', 
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});
```

--------------------------------

### OpenPanel Maintenance Script

Source: https://openpanel.dev/docs/self-hosting/self-hosting

This bash script allows you to rebuild and restart a specific OpenPanel service. You provide the service name as an argument, for example, './rebuild op-dashboard'. This is useful for applying updates or fixing issues with individual services.

```bash
./rebuild <service-name>    # Rebuild and restart a specific service
                            # Example: ./rebuild op-dashboard
```

--------------------------------

### Get Website Metrics with cURL

Source: https://openpanel.dev/docs/api/insights

Example of how to retrieve website metrics using cURL, including specifying the date range and filters. This request requires authentication headers with your client ID and secret.

```bash
curl 'https://api.openpanel.dev/insights/abc123/metrics?range=30d&filters=[{"name":"path","operator":"contains","value":["/product"]}]' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

--------------------------------

### Get Geographic Data - Example Request (Country)

Source: https://openpanel.dev/docs/api/insights

Example cURL request to retrieve country-level geographic data for a specific project. This request includes the project ID, a date range, a limit for results, and authentication headers.

```bash
curl 'https://api.openpanel.dev/insights/abc123/country?range=30d&limit=20' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

--------------------------------

### Get Referrer Data with cURL

Source: https://openpanel.dev/docs/api/insights

Example request using cURL to obtain referrer analytics, including specifying the date range and the limit of results. Authentication is handled through headers.

```bash
curl 'https://api.openpanel.dev/insights/abc123/referrer?range=30d&limit=15' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

--------------------------------

### Initialize OpenPanel SDK in HTML

Source: https://openpanel.dev/docs/self-hosting/self-hosting

This JavaScript snippet demonstrates how to initialize the OpenPanel SDK within an HTML file. It configures the API URL, client ID, and tracking options. The script also loads the OpenPanel JavaScript SDK from a CDN.

```html
<script>
  window.op = window.op||function(...args){(window.op.q=window.op.q||[]).push(args);};
  window.op('init', {
    apiUrl: 'https://your-domain.com/api', 
    clientId: 'YOUR_CLIENT_ID',
    trackScreenViews: true,
    trackOutgoingLinks: true,
    trackAttributes: true,
  });
</script>
<script src="https://openpanel.dev/op1.js" defer async></script>
```

--------------------------------

### Get Top Pages with cURL

Source: https://openpanel.dev/docs/api/insights

Example of retrieving top pages data using cURL, allowing for specification of date range and the number of results per page. Authentication headers are necessary.

```bash
curl 'https://api.openpanel.dev/insights/abc123/pages?range=7d&limit=20' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

--------------------------------

### OpenPanel Web SDK - Strict TypeScript Definition (from SDK)

Source: https://openpanel.dev/docs/sdks/script

This method ensures strict TypeScript typing for the OpenPanel Web SDK by referencing the SDK's own type definitions. It requires installing the SDK via NPM.

```bash
npm install @openpanel/web
```

```typescript
/// <reference types="@openpanel/web" />
```

--------------------------------

### Filter Events with OpenPanel Web SDK (Script Tag)

Source: https://openpanel.dev/docs/sdks/script

Example of implementing an event filter during OpenPanel Web SDK initialization. This filter prevents events from being sent if the user has 'disable_tracking' set in their local storage.

```javascript
window.op('init', {
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
  filter: () => localStorage.getItem('disable_tracking') === undefined,
});
```

--------------------------------

### Initialize OpenPanel Web SDK

Source: https://openpanel.dev/docs/sdks/web

Initializes the OpenPanel Web SDK with provided options. This setup configures the SDK for tracking user behavior, including screen views, outgoing links, and attribute-based events. Requires a `clientId`.

```typescript
import { OpenPanel } from '@openpanel/web';
 
const op = new OpenPanel({
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});
```

--------------------------------

### Filter Configuration Example

Source: https://openpanel.dev/docs/api/insights

Demonstrates the structure for configuring filters to narrow down results in API requests. Filters specify the property name, operator, and values to match.

```json
{
  "name": "property_name",
  "operator": "is|isNot|contains|doesNotContain|startsWith|endsWith|regex",
  "value": ["value1", "value2"]
}
```

--------------------------------

### Initialize OpenPanel Web SDK with Script Tag

Source: https://openpanel.dev/docs/sdks/script

This snippet shows how to initialize the OpenPanel Web SDK by including a script tag in your HTML. Replace 'YOUR_CLIENT_ID' with your actual client ID. It configures options like tracking screen views, outgoing links, and attributes.

```html
<script>
  window.op = window.op||function(...args){(window.op.q=window.op.q||[]).push(args);};
  window.op('init', {
    clientId: 'YOUR_CLIENT_ID',
    trackScreenViews: true,
    trackOutgoingLinks: true,
    trackAttributes: true,
  });
</script>
<script src="https://openpanel.dev/op1.js" defer async></script>
```

--------------------------------

### Enable OpenPanel Registration

Source: https://openpanel.dev/docs/self-hosting/self-hosting

This configuration snippet shows how to enable user registration in OpenPanel by setting the ALLOW_REGISTRATION environment variable to 'true'. By default, registrations are disabled after the first user is created.

```env
ALLOW_REGISTRATION=true
```

--------------------------------

### Update OpenPanel Instance

Source: https://openpanel.dev/docs/self-hosting/self-hosting

This bash script updates your self-hosted OpenPanel instance to the latest version. It typically involves pulling the latest changes from the repository and then running an update process. If the './update' script is missing, you can use 'git pull' followed by './update'.

```bash
./update
```

--------------------------------

### Track Events with OpenPanel Web SDK (Script Tag)

Source: https://openpanel.dev/docs/sdks/script

Demonstrates two methods for tracking events using the OpenPanel Web SDK initialized via a script tag: directly calling `window.op('track')` and using `data-track` attributes on HTML elements.

```html
<button type="button" onclick="window.op('track', 'my_event', { foo: 'bar' })">
  Track event
</button>
```

```html
<button type="button" data-track="my_event" data-foo="bar">Track event</button>
```

--------------------------------

### OpenPanel Web SDK - Simple TypeScript Definition

Source: https://openpanel.dev/docs/sdks/script

Provides a simple global type definition for the OpenPanel Web SDK, allowing basic TypeScript usage without strict type checking. This definition ensures the `window.op` object and its methods are recognized.

```typescript
declare global {
  interface Window {
    op: {
      q?: string[][];
      (...args: [
        'init' | 'track' | 'identify' | 'setGlobalProperties' | 'increment' | 'decrement' | 'clear',
        ...any[]
      ]): void;
    };
  }
}

```

--------------------------------

### Authenticate OpenPanel API Requests

Source: https://openpanel.dev/docs/api/track

All requests to the OpenPanel API require authentication using clientId and clientSecret, which must be included in the request headers. This ensures secure communication with the API.

```bash
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET"
```

--------------------------------

### Identifying Users

Source: https://openpanel.dev/docs/api/track

This endpoint is used to identify users and associate them with a profile. It allows for setting user profile information and custom properties.

```APIDOC
## POST /track (Identify User)

### Description
Used to identify users and associate them with a profile, setting profile information and custom properties.

### Method
POST

### Endpoint
https://api.openpanel.dev/track

### Parameters
#### Headers
- **openpanel-client-id** (string) - Required - Your client ID for authentication.
- **openpanel-client-secret** (string) - Required - Your client secret for authentication.
- **Content-Type** (string) - Required - Must be application/json.
- **x-client-ip** (string) - Optional - IP address for geo-location tracking.
- **user-agent** (string) - Optional - User-agent string for device information.

#### Request Body
- **type** (string) - Required - Must be 'identify'.
- **payload** (object) - Required - Contains user identification details.
  - **profileId** (string) - Required - The unique identifier for the user profile.
  - **firstName** (string) - Optional - The user's first name.
  - **lastName** (string) - Optional - The user's last name.
  - **email** (string) - Optional - The user's email address.
  - **properties** (object) - Optional - Key-value pairs of custom user properties.

### Request Example
```json
{
  "type": "identify",
  "payload": {
    "profileId": "123",
    "firstName": "Joe",
    "lastName": "Doe",
    "email": "joe@doe.com",
    "properties": {
      "tier": "premium"
    }
  }
}
```

### Response
#### Success Response (200)
- **status** (integer) - Indicates success.

#### Response Example
```json
{
  "status": 200
}
```
```

--------------------------------

### Identify Users with OpenPanel Web SDK (Script Tag)

Source: https://openpanel.dev/docs/sdks/script

Shows how to identify a user with the OpenPanel Web SDK using the `window.op('identify')` method. This requires a unique `profileId` and can include optional user details like `firstName`, `lastName`, `email`, and custom `properties`.

```javascript
window.op('identify', {
  profileId: '123', // Required
  firstName: 'Joe',
  lastName: 'Doe',
  email: 'joe@doe.com',
  properties: {
    tier: 'premium',
  },
});
```

--------------------------------

### Set Global Properties with OpenPanel Web SDK (Script Tag)

Source: https://openpanel.dev/docs/sdks/script

This code snippet illustrates how to set global properties that will be appended to every event sent by the OpenPanel Web SDK. This is useful for consistent data like application version or environment.

```javascript
window.op('setGlobalProperties', {
  app_version: '1.0.2',
  environment: 'production',
});
```

--------------------------------

### Get Device & Technology Data

Source: https://openpanel.dev/docs/api/insights

Analyze visitor devices, browsers, and operating systems.

```APIDOC
## GET /insights/{projectId}/device

### Description
Retrieves data broken down by device type.

### Method
GET

### Endpoint
`/insights/{projectId}/device`

### Query Parameters
- **range** (string) - Optional - The time range for the data (e.g., '7d').

### Request Example
```bash
curl 'https://api.openpanel.dev/insights/abc123/device?range=7d' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

### Response
#### Success Response (200)
- **name** (string) - The device type (e.g., 'Desktop', 'Mobile').
- **sessions** (integer) - The number of sessions.
- **bounce_rate** (float) - The bounce rate.
- **avg_session_duration** (float) - The average session duration in seconds.

#### Response Example
```json
[
  {
    "name": "Desktop",
    "sessions": 1500,
    "bounce_rate": 37.5,
    "avg_session_duration": 170.2
  }
]
```

## GET /insights/{projectId}/browser

### Description
Retrieves data broken down by browser.

### Method
GET

### Endpoint
`/insights/{projectId}/browser`

### Query Parameters
- **range** (string) - Optional - The time range for the data (e.g., '7d').

### Response
#### Success Response (200)
- **name** (string) - The browser name (e.g., 'Chrome', 'Firefox').
- **sessions** (integer) - The number of sessions.
- **bounce_rate** (float) - The bounce rate.
- **avg_session_duration** (float) - The average session duration in seconds.

#### Response Example
```json
[
  {
    "name": "Chrome",
    "sessions": 789,
    "bounce_rate": 36.4,
    "avg_session_duration": 162.3
  }
]
```

## GET /insights/{projectId}/browser_version

### Description
Retrieves data broken down by browser version.

### Method
GET

### Endpoint
`/insights/{projectId}/browser_version`

### Query Parameters
- **range** (string) - Optional - The time range for the data (e.g., '7d').
- **prefix** (string) - Optional - Filter by a specific browser.

### Response
#### Success Response (200)
- **prefix** (string) - The browser name.
- **name** (string) - The browser version.
- **sessions** (integer) - The number of sessions.
- **bounce_rate** (float) - The bounce rate.
- **avg_session_duration** (float) - The average session duration in seconds.

#### Response Example
```json
[
  {
    "prefix": "Chrome",
    "name": "118.0.0.0",
    "sessions": 456,
    "bounce_rate": 35.8,
    "avg_session_duration": 165.7
  }
]
```

## GET /insights/{projectId}/os

### Description
Retrieves data broken down by operating system.

### Method
GET

### Endpoint
`/insights/{projectId}/os`

### Query Parameters
- **range** (string) - Optional - The time range for the data (e.g., '7d').

### Response
#### Success Response (200)
- **name** (string) - The operating system name (e.g., 'Windows', 'macOS', 'Android').
- **sessions** (integer) - The number of sessions.
- **bounce_rate** (float) - The bounce rate.
- **avg_session_duration** (float) - The average session duration in seconds.

## GET /insights/{projectId}/os_version

### Description
Retrieves data broken down by operating system version.

### Method
GET

### Endpoint
`/insights/{projectId}/os_version`

### Query Parameters
- **range** (string) - Optional - The time range for the data (e.g., '7d').
- **prefix** (string) - Optional - Filter by a specific operating system.

### Response
#### Success Response (200)
- **prefix** (string) - The operating system name.
- **name** (string) - The operating system version.
- **sessions** (integer) - The number of sessions.
- **bounce_rate** (float) - The bounce rate.
- **avg_session_duration** (float) - The average session duration in seconds.

## GET /insights/{projectId}/brand

### Description
Retrieves data broken down by device brand.

### Method
GET

### Endpoint
`/insights/{projectId}/brand`

### Query Parameters
- **range** (string) - Optional - The time range for the data (e.g., '7d').

### Response
#### Success Response (200)
- **name** (string) - The device brand (e.g., 'Apple', 'Samsung').
- **sessions** (integer) - The number of sessions.
- **bounce_rate** (float) - The bounce rate.
- **avg_session_duration** (float) - The average session duration in seconds.

## GET /insights/{projectId}/model

### Description
Retrieves data broken down by device model.

### Method
GET

### Endpoint
`/insights/{projectId}/model`

### Query Parameters
- **range** (string) - Optional - The time range for the data (e.g., '7d').
- **prefix** (string) - Optional - Filter by a specific device brand.

### Response
#### Success Response (200)
- **prefix** (string) - The device brand.
- **name** (string) - The device model.
- **sessions** (integer) - The number of sessions.
- **bounce_rate** (float) - The bounce rate.
- **avg_session_duration** (float) - The average session duration in seconds.
```

--------------------------------

### Tracking Events

Source: https://openpanel.dev/docs/api/track

This endpoint is used to track custom events with associated properties. It requires authentication and a JSON payload specifying the event name and properties.

```APIDOC
## POST /track

### Description
Used to track custom events with associated properties.

### Method
POST

### Endpoint
https://api.openpanel.dev/track

### Parameters
#### Headers
- **openpanel-client-id** (string) - Required - Your client ID for authentication.
- **openpanel-client-secret** (string) - Required - Your client secret for authentication.
- **Content-Type** (string) - Required - Must be application/json.
- **x-client-ip** (string) - Optional - IP address for geo-location tracking.
- **user-agent** (string) - Optional - User-agent string for device information.

#### Request Body
- **type** (string) - Required - Must be 'track'.
- **payload** (object) - Required - Contains event details.
  - **name** (string) - Required - The name of the event.
  - **properties** (object) - Optional - Key-value pairs of event properties.

### Request Example
```json
{
  "type": "track",
  "payload": {
    "name": "my_event",
    "properties": {
      "foo": "bar"
    }
  }
}
```

### Response
#### Success Response (200)
- **status** (integer) - Indicates success.

#### Response Example
```json
{
  "status": 200
}
```
```

--------------------------------

### Track Events with OpenPanel API

Source: https://openpanel.dev/docs/api/track

Send event data to the OpenPanel API to track user actions. Requires authentication headers and a JSON payload with event type and properties. Can include geo-location and device information via specific headers.

```bash
curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "track",
  "payload": {
    "name": "my_event",
    "properties": {
      "foo": "bar"
    }
  }
}'
```

--------------------------------

### Get Device & Technology Data - API Endpoints

Source: https://openpanel.dev/docs/api/insights

Analyze visitor devices, browsers, operating systems, and their versions. Requires project ID and authentication. Returns data for device type, browser name, OS name, and their respective versions. Version-specific endpoints include a 'prefix' for the parent.

```bash
GET /insights/{projectId}/device
GET /insights/{projectId}/browser
GET /insights/{projectId}/browser_version
GET /insights/{projectId}/os
GET /insights/{projectId}/os_version
GET /insights/{projectId}/brand
GET /insights/{projectId}/model
```

--------------------------------

### Authenticate OpenPanel API with Curl

Source: https://openpanel.dev/docs/api/authentication

Example using curl to authenticate with the OpenPanel API for accessing insights. Requires your project ID and API credentials.

```shell
curl 'https://api.openpanel.dev/insights/{projectId}/metrics' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

--------------------------------

### Identify Users with OpenPanel API

Source: https://openpanel.dev/docs/api/track

Identify users in the OpenPanel API by sending a POST request to the /track endpoint with type 'identify'. Requires authentication and a JSON payload including profileId and optional user properties.

```bash
curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "identify",
  "payload": {
    "profileId": "123",
    "firstName": "Joe",
    "lastName": "Doe",
    "email": "joe@doe.com",
    "properties": {
      "tier": "premium"
    }
  }
}'
```

--------------------------------

### Increment User Profile Property with OpenPanel Web SDK (Script Tag)

Source: https://openpanel.dev/docs/sdks/script

Demonstrates how to increment a numeric property on a user's profile using the `window.op('increment')` method. The `value` parameter specifies the amount to increment by; if omitted, it defaults to 1.

```javascript
window.op('increment', {
  profileId: '1',
  property: 'visits',
  value: 1 // optional
});
```

--------------------------------

### Authenticate and Request Export API Data (cURL)

Source: https://openpanel.dev/docs/api/export

Example cURL request to the OpenPanel Export API's /events endpoint. Requires `openpanel-client-id` and `openpanel-client-secret` headers for authentication. Supports filtering by project ID, event name, date range, pagination, and including additional data like profiles and metadata.

```bash
curl 'https://api.openpanel.dev/export/events?projectId=abc123&event=screen_view&start=2024-04-15&end=2024-04-18&page=1&limit=100&includes=profile,meta' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

--------------------------------

### Clear User Data with OpenPanel Web SDK (Script Tag)

Source: https://openpanel.dev/docs/sdks/script

This snippet shows the command to clear the current user's data from the OpenPanel SDK. This action is useful for scenarios like user logout.

```javascript
window.op('clear');
```

--------------------------------

### Get UTM Campaign Data - API Endpoints

Source: https://openpanel.dev/docs/api/insights

Retrieve marketing campaign performance broken down by UTM parameters (source, medium, campaign, term, content). Requires project ID and client credentials for authentication. Returns campaign performance metrics like sessions, bounce rate, and average session duration.

```bash
GET /insights/{projectId}/utm_source
GET /insights/{projectId}/utm_medium
GET /insights/{projectId}/utm_campaign
GET /insights/{projectId}/utm_term
GET /insights/{projectId}/utm_content
```

--------------------------------

### Initialize OpenPanel Python SDK

Source: https://openpanel.dev/docs/sdks/python

Import and initialize the OpenPanel SDK with your client ID and client secret. This sets up the connection to the OpenPanel service for your application.

```python
from openpanel import OpenPanel

op = OpenPanel(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)
```

--------------------------------

### GET /insights/{projectId}/live

Source: https://openpanel.dev/docs/api/insights

Get the current number of active visitors on your website in real-time.

```APIDOC
## GET /insights/{projectId}/live

### Description
Get the current number of active visitors on your website in real-time.

### Method
GET

### Endpoint
`/insights/{projectId}/live`

### Request Example
```bash
curl 'https://api.openpanel.dev/insights/abc123/live' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

### Response
#### Success Response (200)
- **visitors** (number) - The current number of active visitors.

#### Response Example
```json
{
  "visitors": 23
}
```
```

--------------------------------

### Initialize Server-Side SDK and Track Events

Source: https://openpanel.dev/docs/sdks/nextjs

Initializes the OpenPanel Javascript SDK for server-side event tracking using client and secret credentials. Allows tracking general events or events for specific users by providing a profileId.

```javascript
import { OpenpanelSdk } from '@openpanel/nextjs';

const opServer = new OpenpanelSdk({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}'
});

opServer.event('my_server_event', { ok: '✅' });

// Pass `profileId` to track events for a specific user
opServer.event('my_server_event', { profileId: '123', ok: '✅' });
```

--------------------------------

### Initialize OpenPanel SDK for Next.js Server Components

Source: https://openpanel.dev/docs/sdks/nextjs

Provides a method to initialize the OpenPanel SDK for use in Next.js server components. This approach requires `clientId` and `clientSecret`, and the SDK instance can then be used to track events directly. Note that `clientSecret` should not be exposed on the client side.

```typescript
import { OpenPanel } from '@openpanel/nextjs';

export const op = new OpenPanel({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

// Now you can use `op` to track events
op.track('my_event', { foo: 'bar' });
```

--------------------------------

### Remove Clickhouse Keeper Configuration (YAML)

Source: https://openpanel.dev/docs/self-hosting/changelog

This YAML snippet shows the configuration to remove the Clickhouse Keeper from OpenPanel's self-hosting setup. It involves removing the 'op-zk' service and its associated volumes from the Docker Compose or similar configuration file. Ensure no other parts of your setup depend on this service before removal.

```yaml
services:
  op-zk:
    image: clickhouse/clickhouse-server:24.3.2-alpine
    volumes:
      - op-zk-data:/var/lib/clickhouse
      - ./clickhouse/clickhouse-keeper-config.xml:/etc/clickhouse-server/config.xml
    command: [ 'clickhouse-keeper', '--config-file', '/etc/clickhouse-server/config.xml' ]
    restart: always
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
volumes:
  op-zk-data:
    driver: local
```

--------------------------------

### Decrementing Properties

Source: https://openpanel.dev/docs/api/track

This endpoint allows for decrementing a numeric property associated with a user profile.

```APIDOC
## POST /track (Decrement Property)

### Description
Used to decrement a numeric property associated with a user profile.

### Method
POST

### Endpoint
https://api.openpanel.dev/track

### Parameters
#### Headers
- **openpanel-client-id** (string) - Required - Your client ID for authentication.
- **openpanel-client-secret** (string) - Required - Your client secret for authentication.
- **Content-Type** (string) - Required - Must be application/json.

#### Request Body
- **type** (string) - Required - Must be 'decrement'.
- **payload** (object) - Required - Contains details for decrementing a property.
  - **profileId** (string) - Required - The ID of the profile to update.
  - **property** (string) - Required - The name of the numeric property to decrement.
  - **value** (number) - Required - The amount to decrement the property by.

### Request Example
```json
{
  "type": "decrement",
  "payload": {
    "profileId": "1",
    "property": "visits",
    "value": 1
  }
}
```

### Response
#### Success Response (200)
- **status** (integer) - Indicates success.

#### Response Example
```json
{
  "status": 200
}
```
```

--------------------------------

### Initialize OpenPanel Component in Astro Layout

Source: https://openpanel.dev/docs/sdks/astro

Adds the OpenPanelComponent to your root Astro layout file to initialize the SDK. It allows configuration of client ID, screen view tracking, and optionally user profile ID.

```astro
---
import { OpenPanelComponent } from '@openpanel/astro';
---

<html>
  <head>
    <OpenPanelComponent
      clientId="your-client-id"
      trackScreenViews={true}
      // trackAttributes={true}
      // trackOutgoingLinks={true}
      // If you have a user id, you can pass it here to identify the user
      // profileId={'123'}
    />
  </head>
  <body>
    <slot />
  </body>
</html>
```

--------------------------------

### Incrementing Properties

Source: https://openpanel.dev/docs/api/track

This endpoint allows for incrementing a numeric property associated with a user profile.

```APIDOC
## POST /track (Increment Property)

### Description
Used to increment a numeric property associated with a user profile.

### Method
POST

### Endpoint
https://api.openpanel.dev/track

### Parameters
#### Headers
- **openpanel-client-id** (string) - Required - Your client ID for authentication.
- **openpanel-client-secret** (string) - Required - Your client secret for authentication.
- **Content-Type** (string) - Required - Must be application/json.

#### Request Body
- **type** (string) - Required - Must be 'increment'.
- **payload** (object) - Required - Contains details for incrementing a property.
  - **profileId** (string) - Required - The ID of the profile to update.
  - **property** (string) - Required - The name of the numeric property to increment.
  - **value** (number) - Required - The amount to increment the property by.

### Request Example
```json
{
  "type": "increment",
  "payload": {
    "profileId": "1",
    "property": "visits",
    "value": 1
  }
}
```

### Response
#### Success Response (200)
- **status** (integer) - Indicates success.

#### Response Example
```json
{
  "status": 200
}
```
```

--------------------------------

### Client-side Event Tracking in Astro

Source: https://openpanel.dev/docs/sdks/astro

Shows how to trigger events using the global `op` function or HTML data attributes in Astro. This enables tracking user interactions directly from the client.

```astro
<button onclick="window.op('track', 'clicky')">Click me</button>
<button data-track="clicky" data-prop1="prop1" data-prop2="prop2">Click me</button>
```

--------------------------------

### Get Geographic Data

Source: https://openpanel.dev/docs/api/insights

Understand audience location with country, region, and city breakdowns.

```APIDOC
## GET /insights/{projectId}/country

### Description
Retrieves geographic data broken down by country.

### Method
GET

### Endpoint
`/insights/{projectId}/country`

### Query Parameters
- **range** (string) - Optional - The time range for the data (e.g., '30d').
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```bash
curl 'https://api.openpanel.dev/insights/abc123/country?range=30d&limit=20' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

### Response
#### Success Response (200)
- **name** (string) - The name of the country.
- **sessions** (integer) - The number of sessions.
- **bounce_rate** (float) - The bounce rate.
- **avg_session_duration** (float) - The average session duration in seconds.

#### Response Example
```json
[
  {
    "name": "United States",
    "sessions": 1234,
    "bounce_rate": 38.7,
    "avg_session_duration": 167.4
  }
]
```

## GET /insights/{projectId}/region

### Description
Retrieves geographic data broken down by region.

### Method
GET

### Endpoint
`/insights/{projectId}/region`

### Query Parameters
- **range** (string) - Optional - The time range for the data (e.g., '30d').
- **limit** (integer) - Optional - The maximum number of results to return.
- **prefix** (string) - Optional - Filter by a specific country.

### Response
#### Success Response (200)
- **prefix** (string) - The name of the country.
- **name** (string) - The name of the region.
- **sessions** (integer) - The number of sessions.
- **bounce_rate** (float) - The bounce rate.
- **avg_session_duration** (float) - The average session duration in seconds.

#### Response Example
```json
[
  {
    "prefix": "United States",
    "name": "California",
    "sessions": 456,
    "bounce_rate": 35.2,
    "avg_session_duration": 172.1
  }
]
```

## GET /insights/{projectId}/city

### Description
Retrieves geographic data broken down by city.

### Method
GET

### Endpoint
`/insights/{projectId}/city`

### Query Parameters
- **range** (string) - Optional - The time range for the data (e.g., '30d').
- **limit** (integer) - Optional - The maximum number of results to return.
- **prefix** (string) - Optional - Filter by a specific country or region.

### Response
#### Success Response (200)
- **prefix** (string) - The name of the country or region.
- **name** (string) - The name of the city.
- **sessions** (integer) - The number of sessions.
- **bounce_rate** (float) - The bounce rate.
- **avg_session_duration** (float) - The average session duration in seconds.
```