Medama Analytics

https://oss.medama.io
Admin
Medama Analytics is an open-source, self-hostable website analytics platform offering real-time...
Tokens:41,483
Snippets:186
Trust Score:5.1
Update:7 months ago
Show doc for...
Tokens:
Raw
### Start Analytics Server Example Usage

Source: https://oss.medama.io/config/cli

Provides an example of how to use the 'start' command with specific flags for the Medama IO CLI. This example demonstrates setting environment variable usage, specifying the port, logger format, log level, and allowed CORS origins.

```sh
./medama-executable start -env -port=8080 -logger=pretty -level=debug -corsorigins=http://localhost:8080,http://localhost:3000
```

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

### Start Docker Compose Services

Source: https://oss.medama.io/deployment/docker

Starts the services defined in the 'docker-compose.yml' file in detached mode. This command is used after creating the docker-compose.yml file to bring up the Medama container.

```sh
docker-compose up -d
```

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

### Install Tracking Snippet (HTML)

Source: https://oss.medama.io/config/tracking-snippet

Embed this script tag in the `<head>` of your website to install the tracking snippet. It ensures the script is loaded after the HTML is parsed.

```html
<script defer src="https://[your-analytics-server].com/script.js"></script>
```

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

### Start Server with Automatic SSL Setup

Source: https://oss.medama.io/deployment/ssl

Automatically provisions SSL certificates for a specified domain and redirects HTTP to HTTPS. Requires the server to run on ports 80 and 443, and the domain must be publicly accessible and resolve to the server.

```sh
./medama start -autossl example.com
```

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

### GET /websites/{hostname}

Source: https://oss.medama.io/api-reference/website/get-website

Retrieves detailed information about a specific website, including visitor statistics.

```APIDOC
## GET /websites/{hostname}

### Description
Get website details for an individual website.

### Method
GET

### Endpoint
/websites/{hostname}

### Parameters
#### Path Parameters
- **hostname** (string) - Required - Hostname for the website.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **hostname** (string) - The hostname of the website.
- **summary** (object) - An object containing summary statistics.
  - **visitors** (integer) - The total number of visitors.

#### Response Example
```json
{
  "hostname": "example.com",
  "summary": {
    "visitors": 1500
  }
}
```

#### Error Responses
- **400 Bad Request**: Returned if the request is malformed.
- **401 Unauthorised**: Returned if the user is not authenticated.
- **404 Not Found**: Returned if the website does not exist.
- **500 Internal Server Error**: Returned if an unexpected error occurs on the server.
```

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

### Get OS Stats

Source: https://oss.medama.io/api-reference/stats/get-os-stats

Fetches a list of operating systems along with their performance metrics and other relevant statistics.

```APIDOC
## GET /os/stats

### Description
Get a list of OS and their stats.

### Method
GET

### Endpoint
/os/stats

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of OS stats to return.
- **offset** (integer) - Optional - The number of OS stats to skip before starting to collect the result set.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **os_name** (string) - The name of the operating system.
- **cpu_usage** (float) - The current CPU utilization percentage.
- **memory_usage** (float) - The current memory utilization percentage.
- **disk_usage** (float) - The current disk utilization percentage.

#### Response Example
```json
{
  "os_stats": [
    {
      "os_name": "Linux",
      "cpu_usage": 0.75,
      "memory_usage": 0.60,
      "disk_usage": 0.85
    },
    {
      "os_name": "Windows",
      "cpu_usage": 0.65,
      "memory_usage": 0.55,
      "disk_usage": 0.70
    }
  ]
}
```
```

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

### Get Device Stats

Source: https://oss.medama.io/api-reference/stats/get-device-stats

Fetches a list of devices and their corresponding statistics.

```APIDOC
## GET /devices/stats

### Description
Get a list of devices and their stats.

### Method
GET

### Endpoint
/devices/stats

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of devices to return.
- **offset** (integer) - Optional - The number of devices to skip before starting to collect the result set.

### Request Example
```
GET /devices/stats?limit=10&offset=0
```

### Response
#### Success Response (200)
- **devices** (array) - A list of device objects, each containing stats.
  - **id** (string) - The unique identifier for the device.
  - **name** (string) - The name of the device.
  - **stats** (object) - An object containing various statistics for the device.
    - **cpu_usage** (number) - The current CPU usage percentage.
    - **memory_usage** (number) - The current memory usage percentage.
    - **disk_usage** (number) - The current disk usage percentage.

#### Response Example
```json
{
  "devices": [
    {
      "id": "device-123",
      "name": "Server Alpha",
      "stats": {
        "cpu_usage": 75.5,
        "memory_usage": 60.2,
        "disk_usage": 85.1
      }
    },
    {
      "id": "device-456",
      "name": "Workstation Beta",
      "stats": {
        "cpu_usage": 40.1,
        "memory_usage": 45.8,
        "disk_usage": 55.3
      }
    }
  ]
}
```
```

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

### Run Medama.io Binary

Source: https://oss.medama.io/deployment/single-binary

Command to start the Medama.io analytics instance after downloading the binary. This command initializes database files if they don't exist.

```sh
./<path-to-executable> start
```

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

### GET /websites

Source: https://oss.medama.io/api-reference/website/list-websites

Retrieves a list of all websites associated with the authenticated user. Optionally, a summary of statistics can be included.

```APIDOC
## GET /websites

### Description
Get a list of all websites from the user. This endpoint allows you to retrieve a collection of websites linked to your account. You can also request a summary of statistics for these websites.

### Method
GET

### Endpoint
/websites

### Parameters
#### Query Parameters
- **summary** (boolean) - Optional - Return a summary of the stats. Defaults to false.

#### Request Body
This endpoint does not accept a request body.

### Response
#### Success Response (200)
- **hostname** (string) - The hostname of the website.
- **summary** (object) - An object containing website statistics.
  - **visitors** (integer) - The number of visitors for the website.

#### Response Example
```json
[
  {
    "hostname": "example.com",
    "summary": {
      "visitors": 1500
    }
  }
]
```

#### Error Responses
- **400 Bad Request**: Returned if the request is malformed.
- **401 Unauthorised**: Returned if the user is not authenticated.
- **404 Not Found**: Returned if the requested resource is not found.
- **500 Internal Server Error**: Returned if an unexpected error occurs on the server.
```

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

### GET /website/{hostname}/os

Source: https://oss.medama.io/api-reference/stats/get-os-stats

Retrieves operating system statistics for a given website hostname. This endpoint allows filtering by various parameters to narrow down the results.

```APIDOC
## GET /website/{hostname}/os

### Description
Retrieves operating system statistics for a given website hostname. This endpoint allows filtering by various parameters to narrow down the results.

### Method
GET

### Endpoint
/website/{hostname}/os

### Parameters
#### Path Parameters
- **hostname** (string) - Required - Hostname for the website.

#### Query Parameters
- **summary** (boolean) - Optional - Return a summary of the stats. Defaults to false.
- **start** (string) - Optional - Period start date using date-time notation in RFC3339 format, for example, (2017-07-21T17:32:28Z).
- **end** (string) - Optional - Period end date using date-time notation in RFC3339 format, for example, (2017-07-21T17:32:28Z).
- **path** (object) - Optional - Filter by page path.
- **referrer** (object) - Optional - Filter by referrer URL.
- **utm_source** (object) - Optional - Filter by UTM source.
- **utm_medium** (object) - Optional - Filter by UTM medium.
- **utm_campaign** (object) - Optional - Filter by UTM campaign.
- **browser** (object) - Optional - Filter by browser.
- **os** (object) - Optional - Filter by operating system.
- **device** (object) - Optional - Filter by device.
- **country** (object) - Optional - Filter by country.
- **language** (object) - Optional - Filter by language.
- **property_name** (object) - Optional - Filter by property name.
- **property_value** (object) - Optional - Filter by property value.
- **limit** (integer) - Optional - Maximum number of results to return.
- **offset** (integer) - Optional - Number of results to skip.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **stats** (array) - List of OS and their corresponding stats.
- **X-Api-Commit** (string) - The commit hash of the API.

#### Response Example
```json
{
  "stats": [
    {
      "os": "Windows",
      "count": 1500,
      "percentage": 0.60
    },
    {
      "os": "macOS",
      "count": 750,
      "percentage": 0.30
    },
    {
      "os": "Linux",
      "count": 250,
      "percentage": 0.10
    }
  ]
}
```

#### Error Responses
- **400** - Bad Request Error
- **401** - Unauthorised Error
- **403** - Forbidden Error
- **404** - Not Found Error
- **500** - Internal Server Error
```

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

### Get User Info

Source: https://oss.medama.io/api-reference/user/get-user-info

Retrieve the information of the user with the matching user ID.

```APIDOC
## GET /users/{userId}

### Description
Retrieve the information of the user with the matching user ID.

### Method
GET

### Endpoint
/users/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the user.
- **username** (string) - The username of the user.
- **email** (string) - The email address of the user.

#### Response Example
{
  "id": "user123",
  "username": "johndoe",
  "email": "johndoe@example.com"
}
```

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

### Get Website Time Stats - OpenAPI Specification

Source: https://oss.medama.io/api-reference/stats/get-time-stats

This OpenAPI 3.0 specification defines the 'get /website/{hostname}/time' endpoint. It allows retrieval of time-based statistics for a given website hostname, supporting various filtering parameters and returning detailed time statistics in JSON format. Authentication is handled via session cookies.

```yaml
openapi: 3.0.3
info:
  title: Medama Analytics API
  version: 0.5.0
  description: |
    This is the Medama Analytics OpenAPI 3.0 specification.
  contact:
    email: hello@ayuhito.com
    name: Medama Analytics
    url: https://medama.io/contact
  license:
    url: https://github.com/medama-io/medama/blob/main/core/LICENSE
    name: Apache License 2.0
servers:
  - url: http://localhost:8080
    description: Local Server
security: []
tags:
  - name: Authentication
    description: Authentication
  - name: Event
    description: Page Events
  - name: User
    description: User Management
  - name: Website
    description: Website Management
  - name: Stats
    description: Statistics
paths:
  /website/{hostname}/time:
    get:
      tags:
        - Stats
      summary: Get Time Stats
      description: Get a list of pages and their time stats.
      operationId: get-website-id-time
      parameters:
        - $ref: '#/components/parameters/SessionAuth'
        - $ref: '#/components/parameters/Hostname'
        - $ref: '#/components/parameters/Summary'
        - $ref: '#/components/parameters/PeriodStart'
        - $ref: '#/components/parameters/PeriodEnd'
        - $ref: '#/components/parameters/Path'
        - $ref: '#/components/parameters/Referrer'
        - $ref: '#/components/parameters/UTMSource'
        - $ref: '#/components/parameters/UTMMedium'
        - $ref: '#/components/parameters/UTMCampaign'
        - $ref: '#/components/parameters/Browser'
        - $ref: '#/components/parameters/OS'
        - $ref: '#/components/parameters/Device'
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Language'
        - $ref: '#/components/parameters/PropertyName'
        - $ref: '#/components/parameters/PropertyValue'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: OK
          headers:
            X-Api-Commit:
              $ref: '#/components/headers/X-Api-Commit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsTime'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorisedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - CookieAuth: []
components:
  parameters:
    SessionAuth:
      name: _me_sess
      in: cookie
      description: Session token for authentication.
      required: true
      schema:
        type: string
        example: _me_sess=token; Path=/; HttpOnly; SameSite=Lax; Secure
    Hostname:
      name: hostname
      in: path
      description: Hostname for the website.
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 253
        format: hostname
    Summary:
      name: summary
      in: query
      description: Return a summary of the stats.
      required: false
      schema:
        type: boolean
        default: false
    PeriodStart:
      name: start
      in: query
      description: >-
        Period start date using date-time notation in RFC3339 format, for
        example, (2017-07-21T17:32:28Z).
      required: false
      schema:
        type: string
        format: date-time
    PeriodEnd:
      name: end
      in: query
      description: >-
        Period end date using fdate-time notation in RFC3339 format, for
        example, (2017-07-21T17:32:28Z).
      required: false
      schema:
        type: string
        format: date-time
    Path:
      name: path
      in: query
      description: Path of the page.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: '#/components/schemas/FilterString'
    Referrer:
      name: referrer
      in: query
      description: Referrer URL of the page hit.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: '#/components/schemas/FilterString'
    UTMSource:
      name: utm_source
      in: query
      description: UTM source of the page hit.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: '#/components/schemas/FilterString'
    UTMMedium:
      name: utm_medium
      in: query
      description: UTM medium of the page hit.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:
        $ref: '#/components/schemas/FilterString'
    UTMCampaign:
      name: utm_campaign
      in: query
      description: UTM campaign of the page hit.
      required: false
      style: deepObject
      explode: true
      allowReserved: true
      schema:

```

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

### GET /website/{hostname}/time

Source: https://oss.medama.io/api-reference/stats/get-time-stats

Retrieves time-based statistics for a specific website, allowing filtering by various parameters.

```APIDOC
## GET /website/{hostname}/time

### Description
Get a list of pages and their time stats. This endpoint allows for detailed filtering to analyze website performance over specific periods and segments.

### Method
GET

### Endpoint
/website/{hostname}/time

### Parameters
#### Path Parameters
- **hostname** (string) - Required - Hostname for the website.

#### Query Parameters
- **summary** (boolean) - Optional - Return a summary of the stats. Defaults to false.
- **start** (string) - Optional - Period start date using date-time notation in RFC3339 format, for example, (2017-07-21T17:32:28Z).
- **end** (string) - Optional - Period end date using date-time notation in RFC3339 format, for example, (2017-07-21T17:32:28Z).
- **path** (object) - Optional - Filter by page path. Accepts deepObject style.
- **referrer** (object) - Optional - Filter by referrer URL. Accepts deepObject style.
- **utm_source** (object) - Optional - Filter by UTM source. Accepts deepObject style.
- **utm_medium** (object) - Optional - Filter by UTM medium. Accepts deepObject style.
- **utm_campaign** (object) - Optional - Filter by UTM campaign. Accepts deepObject style.
- **browser** (object) - Optional - Filter by browser. Accepts deepObject style.
- **os** (object) - Optional - Filter by operating system. Accepts deepObject style.
- **device** (object) - Optional - Filter by device type. Accepts deepObject style.
- **country** (object) - Optional - Filter by country. Accepts deepObject style.
- **language** (object) - Optional - Filter by language. Accepts deepObject style.
- **property_name** (object) - Optional - Filter by custom property name. Accepts deepObject style.
- **property_value** (object) - Optional - Filter by custom property value. Accepts deepObject style.
- **limit** (integer) - Optional - Maximum number of results to return.
- **offset** (integer) - Optional - Number of results to skip.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **X-Api-Commit** (string) - Description of the API commit hash.
- **StatsTime** (object) - Schema containing time-based statistics. (See components/schemas/StatsTime for details)

#### Response Example
```json
{
  "example": "response body"
}
```

#### Error Responses
- **400** - Bad Request (See components/responses/BadRequestError for details)
- **401** - Unauthorized (See components/responses/UnauthorisedError for details)
- **404** - Not Found (See components/responses/NotFoundError for details)
- **500** - Internal Server Error (See components/responses/InternalServerError for details)
```

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

### Start Analytics Server CLI Flags

Source: https://oss.medama.io/config/cli

Defines the available flags for the 'start' command in the Medama IO CLI. These flags control various aspects of the analytics server, such as database paths, SSL configuration, CORS origins, logging levels, and port settings. The 'autossl' flag requires specific port configurations and domain accessibility.

```sh
Usage of start:
  -analyticsdb string
    	Path to analytics database. (default "./me_analytics.db")
  -appdb string
    	Path to app database. (default "./me_meta.db")
  -autossl string
    	Automatically provision SSL certificates to the specified domain and redirect HTTP requests to HTTPS.

	Requires the server to run on ports 80 and 443. The domain must be publicly accessible and resolve to the server.
  -autosslemail string
    	Email address to optionally send SSL certificate notifications.
  -corsorigins string
    	Comma separated list of allowed CORS origins on API routes. Useful for external dashboards that may host the frontend on a different domain.
  -demo
    	Enable demo mode restricting all POST/PATCH/DELETE actions (except login).
  -env
    	Opt-in to allow environment variables to be used for configuration. Flags will still override environment variables.
  -level string
    	Logger level (debug, info, warn, error) (default "info")
  -logger string
    	Logger format (json, pretty) (default "json")
  -port int
    	Port to listen on. (default 8080)
  -profiler
    	Enable debug profiling.
```

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

### GET /website/{hostname}/devices

Source: https://oss.medama.io/api-reference/stats/get-device-stats

Retrieves a list of devices and their associated statistics for a given website hostname. This endpoint allows filtering and aggregation of device data over specified periods.

```APIDOC
## GET /website/{hostname}/devices

### Description
Get a list of devices and their stats.

### Method
GET

### Endpoint
/website/{hostname}/devices

### Parameters
#### Path Parameters
- **hostname** (string) - Required - Hostname for the website.

#### Query Parameters
- **summary** (boolean) - Optional - Return a summary of the stats. Defaults to false.
- **start** (string) - Optional - Period start date using date-time notation in RFC3339 format, for example, (2017-07-21T17:32:28Z).
- **end** (string) - Optional - Period end date using date-time notation in RFC3339 format, for example, (2017-07-21T17:32:28Z).
- **path** (FilterString) - Optional - Path of the page.
- **referrer** (FilterString) - Optional - Referrer URL of the page hit.
- **utm_source** (FilterString) - Optional - UTM source of the page hit.
- **utm_medium** (FilterString) - Optional - UTM medium of the page hit.
- **utm_campaign** (FilterString) - Optional - UTM campaign of the page hit.
- **browser** (FilterString) - Optional - Browser of the page hit.
- **os** (FilterString) - Optional - Operating system of the page hit.
- **device** (FilterString) - Optional - Device type of the page hit.
- **country** (FilterString) - Optional - Country of the page hit.
- **language** (FilterString) - Optional - Language of the page hit.
- **property_name** (FilterString) - Optional - Custom property name to filter by.
- **property_value** (FilterString) - Optional - Custom property value to filter by.
- **limit** (integer) - Optional - Maximum number of results to return.
- **offset** (integer) - Optional - Number of results to skip.

#### Request Body
This endpoint does not accept a request body.

### Request Example
```http
GET /website/example.com/devices?summary=true&start=2023-01-01T00:00:00Z&end=2023-01-31T23:59:59Z
```

### Response
#### Success Response (200)
- **devices** (array) - An array of device statistics.
  - **device** (string) - The type of device (e.g., 'desktop', 'mobile', 'tablet').
  - **sessions** (integer) - The number of sessions for this device type.
  - **pageviews** (integer) - The number of pageviews for this device type.
  - **visitors** (integer) - The number of unique visitors for this device type.

#### Response Example
```json
{
  "devices": [
    {
      "device": "desktop",
      "sessions": 1500,
      "pageviews": 4500,
      "visitors": 1000
    },
    {
      "device": "mobile",
      "sessions": 2000,
      "pageviews": 5000,
      "visitors": 1200
    }
  ]
}
```

#### Error Responses
- **400** - Bad Request: Invalid input parameters.
- **401** - Unauthorized: Authentication failed.
- **403** - Forbidden: Insufficient permissions.
- **404** - Not Found: The specified website or resource was not found.
- **500** - Internal Server Error: An unexpected error occurred on the server.
```

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

### GET /user

Source: https://oss.medama.io/api-reference/user/get-user-info

Retrieves the information of the user with the matching user ID. Requires session authentication via a cookie.

```APIDOC
## GET /user

### Description
Retrieve the information of the user with the matching user ID.

### Method
GET

### Endpoint
/user

### Parameters
#### Query Parameters
- **_me_sess** (string) - Required - Session token for authentication. Example: `_me_sess=token; Path=/; HttpOnly; SameSite=Lax; Secure`

### Request Example
```json
{
  "example": "No request body for GET /user"
}
```

### Response
#### Success Response (200)
- **username** (string) - The username of the user.
- **settings** (object) - The user's settings.
  - **language** (string) - The user's preferred language. Enum: `en`. Default: `en`.
  - **script_type** (array) - The type of scripts to be executed. Items: `default`, `click-events`, `page-events`. Unique items.
- **dateCreated** (integer) - The timestamp when the user was created.
- **dateUpdated** (integer) - The timestamp when the user was last updated.

#### Response Example
```json
{
  "username": "john_doe",
  "settings": {
    "language": "en",
    "script_type": [
      "default",
      "click-events"
    ]
  },
  "dateCreated": 1678886400,
  "dateUpdated": 1678886400
}
```

#### Error Responses
- **400 Bad Request**
- **401 Unauthorised**
- **404 Not Found**
- **500 Internal Server Error**
```

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

### GET /websites/oss_medama_io/stats/devices

Source: https://oss.medama.io/api-reference/stats/get-device-stats

Retrieves statistics for website visitors broken down by device type. Supports filtering and pagination.

```APIDOC
## GET /websites/oss_medama_io/stats/devices

### Description
Retrieves statistics for website visitors broken down by device type. Supports filtering and pagination.

### Method
GET

### Endpoint
/websites/oss_medama_io/stats/devices

### Parameters
#### Query Parameters
- **browser** (FilterString) - Optional - Browser name.
- **os** (FilterString) - Optional - Operating system name.
- **device** (FilterString) - Optional - Device type.
- **country** (FilterString) - Optional - Country name.
- **language** (FilterString) - Optional - Language code.
- **prop_name** (FilterString) - Optional - Name of the property.
- **prop_value** (FilterString) - Optional - Value of the property.
- **limit** (integer) - Optional - Limit the number of results. Minimum: 1, Maximum: 5000.
- **offset** (integer) - Optional - Offset the results paired with the limit parameter. Minimum: 0, Maximum: 5000.

### Headers
- **X-Api-Commit** (string) - Optional - A custom header used to identify the commit of the API. This can be used to force reload the client if the API has been updated.

### Response
#### Success Response (200)
- **device** (string) - Device name.
- **visitors** (integer) - Number of unique visitors from device.
- **visitors_percentage** (number) - Percentage of unique visitors from device relative to all visitors.
- **bounce_percentage** (number) - Bounce rate percentage from device.
- **duration** (integer) - Total time spent on page from device in milliseconds.

#### Response Example
```json
[
  {
    "device": "desktop",
    "visitors": 1500,
    "visitors_percentage": 0.75,
    "bounce_percentage": 0.45,
    "duration": 120000
  },
  {
    "device": "mobile",
    "visitors": 500,
    "visitors_percentage": 0.25,
    "bounce_percentage": 0.60,
    "duration": 90000
  }
]
```

#### Error Response (400)
- **error.code** (integer) - Error code.
- **error.message** (string) - Error message.

#### Error Response (401)
- **error.code** (integer) - Error code.
- **error.message** (string) - Error message.
```

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

### GET /website/{hostname}/languages

Source: https://oss.medama.io/api-reference/stats/get-language-stats

Retrieves a list of languages and their associated statistics for a given website hostname. This endpoint allows filtering by various parameters to refine the statistics.

```APIDOC
## GET /website/{hostname}/languages

### Description
Get a list of languages and their stats for a specific website.

### Method
GET

### Endpoint
`/website/{hostname}/languages`

### Parameters
#### Path Parameters
- **hostname** (string) - Required - Hostname for the website.

#### Query Parameters
- **locale** (boolean) - Optional - Whether to return the language name or the language dialect/locale. Defaults to `false`.
- **_me_sess** (string) - Required - Session token for authentication.
- **summary** (boolean) - Optional - Return a summary of the stats. Defaults to `false`.
- **start** (string) - Optional - Period start date using date-time notation in RFC3339 format.
- **end** (string) - Optional - Period end date using date-time notation in RFC3339 format.
- **path** (FilterString) - Optional - Filter by page path.
- **referrer** (FilterString) - Optional - Filter by referrer URL.
- **utm_source** (FilterString) - Optional - Filter by UTM source.
- **utm_medium** (FilterString) - Optional - Filter by UTM medium.
- **utm_campaign** (FilterString) - Optional - Filter by UTM campaign.
- **browser** (FilterString) - Optional - Filter by browser.
- **os** (FilterString) - Optional - Filter by operating system.
- **device** (FilterString) - Optional - Filter by device type.
- **country** (FilterString) - Optional - Filter by country.
- **language** (FilterString) - Optional - Filter by language.
- **property_name** (FilterString) - Optional - Filter by property name.
- **property_value** (FilterString) - Optional - Filter by property value.
- **limit** (integer) - Optional - Maximum number of results to return.
- **offset** (integer) - Optional - Number of results to skip.

### Request Example
```json
{
  "example": "(No request body for GET request)"
}
```

### Response
#### Success Response (200)
- **X-Api-Commit** (string) - Description of the API commit hash.
- **StatsLanguages** (object) - Schema containing language statistics.

#### Response Example
```json
{
  "example": "(JSON response body with language statistics will be returned here)"
}
```

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **403** - Forbidden
- **404** - Not Found
- **500** - Internal Server Error
```

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

### GET /websites/oss_medama_io/stats/os

Source: https://oss.medama.io/api-reference/stats/get-os-stats

Retrieves statistics for operating systems, including visitor counts and percentages. This endpoint allows filtering by various parameters to refine the results.

```APIDOC
## GET /websites/oss_medama_io/stats/os

### Description
Retrieves statistics for operating systems, including visitor counts and percentages. This endpoint allows filtering by various parameters to refine the results.

### Method
GET

### Endpoint
/websites/oss_medama_io/stats/os

### Parameters
#### Query Parameters
- **browser** (FilterString) - Optional - Browser name.
- **os** (FilterString) - Optional - Operating system name.
- **device** (FilterString) - Optional - Device type.
- **country** (FilterString) - Optional - Country name.
- **language** (FilterString) - Optional - Language code.
- **prop_name** (FilterString) - Optional - Name of the property.
- **prop_value** (FilterString) - Optional - Value of the property.
- **limit** (integer) - Optional - Limit the number of results. Minimum: 1, Maximum: 5000.
- **offset** (integer) - Optional - Offset the results paired with the limit parameter. Minimum: 0, Maximum: 5000.

### Headers
- **X-Api-Commit** (string) - Optional - A custom header used to identify the commit of the API. This can be used to force reload the client if the API has been updated.

### Response
#### Success Response (200)
- **os** (string) - OS name.
- **visitors** (integer) - Number of unique visitors from OS.
- **visitors_percentage** (number) - Percentage of unique visitors from OS relative to all visitors.
- **bounce_percentage** (number) - Bounce rate percentage from OS.
- **duration** (integer) - Total time spent on page from OS in milliseconds.

#### Response Example
```json
[
  {
    "os": "Windows",
    "visitors": 15000,
    "visitors_percentage": 0.60,
    "bounce_percentage": 0.45,
    "duration": 120000
  },
  {
    "os": "macOS",
    "visitors": 7500,
    "visitors_percentage": 0.30,
    "bounce_percentage": 0.30,
    "duration": 180000
  }
]
```

#### Error Response (400)
- **error.code** (integer) - Error code.
- **error.message** (string) - Error message.

#### Error Response Example
```json
{
  "error": {
    "code": 400,
    "message": "Invalid parameter value."
  }
}
```

#### Error Response (401)
- **error.code** (integer) - Error code.
- **error.message** (string) - Error message.

#### Error Response Example
```json
{
  "error": {
    "code": 401,
    "message": "Authentication failed."
  }
}
```
```

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

### GET /website/{hostname}/countries

Source: https://oss.medama.io/api-reference/stats/get-country-stats

Retrieves a list of countries and their associated statistics for a given website hostname. This endpoint allows filtering by various parameters to narrow down the results.

```APIDOC
## GET /website/{hostname}/countries

### Description
Get a list of countries and their stats.

### Method
GET

### Endpoint
/website/{hostname}/countries

### Parameters
#### Path Parameters
- **hostname** (string) - Required - Hostname for the website.

#### Query Parameters
- **summary** (boolean) - Optional - Return a summary of the stats. Defaults to false.
- **start** (string) - Optional - Period start date using date-time notation in RFC3339 format, for example, (2017-07-21T17:32:28Z).
- **end** (string) - Optional - Period end date using date-time notation in RFC3339 format, for example, (2017-07-21T17:32:28Z).
- **path** (object) - Optional - Filter by page path.
- **referrer** (object) - Optional - Filter by referrer URL.
- **utm_source** (object) - Optional - Filter by UTM source.
- **utm_medium** (object) - Optional - Filter by UTM medium.
- **utm_campaign** (object) - Optional - Filter by UTM campaign.
- **browser** (object) - Optional - Filter by browser.
- **os** (object) - Optional - Filter by operating system.
- **device** (object) - Optional - Filter by device type.
- **country** (object) - Optional - Filter by country.
- **language** (object) - Optional - Filter by language.
- **property_name** (object) - Optional - Filter by property name.
- **property_value** (object) - Optional - Filter by property value.
- **limit** (integer) - Optional - Maximum number of results to return.
- **offset** (integer) - Optional - Number of results to skip.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **countries** (array) - List of country statistics.
  - **country** (string) - The name of the country.
  - **visitors** (integer) - The number of unique visitors from this country.
  - **pageviews** (integer) - The total number of pageviews from this country.
  - **bounce_rate** (number) - The bounce rate for visitors from this country.
  - **avg_duration** (number) - The average session duration for visitors from this country.

#### Response Example
```json
{
  "countries": [
    {
      "country": "United States",
      "visitors": 1500,
      "pageviews": 3000,
      "bounce_rate": 0.45,
      "avg_duration": 120.5
    },
    {
      "country": "Canada",
      "visitors": 800,
      "pageviews": 1500,
      "bounce_rate": 0.40,
      "avg_duration": 135.2
    }
  ]
}
```

#### Error Responses
- **400 Bad Request**: Returned if the request parameters are invalid.
- **401 Unauthorized**: Returned if the authentication token is missing or invalid.
- **403 Forbidden**: Returned if the authenticated user does not have permission to access the resource.
- **404 Not Found**: Returned if the specified hostname does not exist.
- **500 Internal Server Error**: Returned if there was an error on the server.
```

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

### Create and Navigate Directory (Bash)

Source: https://oss.medama.io/deployment/fly

Creates a new directory for your Medama deployment and navigates into it. This directory will house your `fly.toml` configuration file.

```bash
mkdir medama-analytics
cd medama-analytics
```

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

### Launch Medama Application on Fly.io (Bash)

Source: https://oss.medama.io/deployment/fly

Deploys the Medama application to Fly.io by cloning an example repository. This command initiates the deployment process and prompts for application configuration.

```bash
fly launch --from https://github.com/medama-io/example-fly-io
```

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

### Docker Compose for Medama

Source: https://oss.medama.io/deployment/docker

Defines a Docker Compose setup for Medama. It specifies the image to use, maps port 8080, and defines a named volume 'medama-data' for persistent storage. This configuration simplifies multi-container deployments.

```yaml
version: '3'
services:
    medama:
        image: ghcr.io/medama-io/medama:latest
        ports:
            - "8080:8080"
        volumes:
            - medama-data:/app/data

volumes:
    medama-data:
```

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

### Grant Port Binding Permissions (Linux)

Source: https://oss.medama.io/deployment/ssl

Allows a binary to bind to privileged ports (80 and 443) without requiring root privileges on Linux systems. This is necessary for the automatic SSL setup feature to function correctly.

```sh
sudo setcap cap_net_bind_service=+ep /path/to/your/binary
```

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

### Documentation Index

Source: https://oss.medama.io/api-reference/stats/get-utm-medium-stats

Fetches the complete documentation index for the Medama project.

```APIDOC
## GET /websites/oss_medama_io/documentation_index

### Description
Fetch the complete documentation index at: https://medama.mintlify.app/llms.txt. Use this file to discover all available pages before exploring further.

### Method
GET

### Endpoint
/websites/oss_medama_io/documentation_index

### Parameters
None

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **documentation_url** (string) - The URL to the complete documentation index file.

#### Response Example
```json
{
  "documentation_url": "https://medama.mintlify.app/llms.txt"
}
```
```

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

### Get Stat Summary

Source: https://oss.medama.io/api-reference/stats/get-stat-summary

Retrieves a summary of the website's statistics.

```APIDOC
## GET /websites/oss_medama_io/stats

### Description
Get a summary of the website's stats.

### Method
GET

### Endpoint
/websites/oss_medama_io/stats

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **stats** (object) - An object containing various website statistics.
  - **page_views** (integer) - The total number of page views.
  - **unique_visitors** (integer) - The number of unique visitors.
  - **bounce_rate** (float) - The website's bounce rate.

#### Response Example
```json
{
  "stats": {
    "page_views": 15000,
    "unique_visitors": 7500,
    "bounce_rate": 0.45
  }
}
```
```
Tokens:
Raw