pieowlDocs
pieowl.comSign inStart free trial
Python

Python

Send events to Pieowl from Python with the HTTP API. Track events, identify users and record revenue using only the standard library.

View as Markdown

Pieowl doesn't ship a Python SDK. You send events from Python with a plain HTTP request to the Track API. The example below uses only the standard library, so there is nothing to install.

Looking for a step-by-step tutorial? Read the Python analytics guide.

Before you start

You need a client ID and a client secret. Find them in the dashboard under Settings → Developers → Keys. Server requests must include the secret, so keep it on your server and load it from an environment variable.

Send an event

Every request is a POST to https://api.pieowl.com/track with a JSON body of { "type": ..., "payload": ... }.

pieowl.py
import json
import os
import urllib.request

PIEOWL_URL = "https://api.pieowl.com/track"


def pieowl_send(event_type, payload, client_ip=None, user_agent=None):
    headers = {
        "Content-Type": "application/json",
        "pieowl-client-id": os.environ["PIEOWL_CLIENT_ID"],
        "pieowl-client-secret": os.environ["PIEOWL_CLIENT_SECRET"],
    }
    # Optional: forward the visitor's IP and user agent for location and device data
    if client_ip:
        headers["pieowl-client-ip"] = client_ip
    if user_agent:
        headers["user-agent"] = user_agent

    body = json.dumps({"type": event_type, "payload": payload}).encode()
    request = urllib.request.Request(PIEOWL_URL, data=body, headers=headers, method="POST")
    with urllib.request.urlopen(request, timeout=5) as response:
        return response.status

Usage

Tracking events

python
pieowl_send("track", {
    "name": "signup",
    "profileId": "user_123",  # optional
    "properties": {"plan": "pro"},
})

Identifying users

python
pieowl_send("identify", {
    "profileId": "user_123",  # required
    "firstName": "Joe",
    "lastName": "Doe",
    "email": "joe@doe.com",
    "properties": {"tier": "premium"},
})

Incrementing and decrementing properties

value is optional and defaults to 1.

python
pieowl_send("increment", {"profileId": "user_123", "property": "visits", "value": 1})
pieowl_send("decrement", {"profileId": "user_123", "property": "credits", "value": 1})

Tracking revenue

A purchase is a revenue event with these properties:

  • __amount: in normal units, like 49.99, not cents.
  • __currency: an ISO 4217 code, like EUR. Optional, your site currency by default.
  • __orderId: your order number. The same order sent twice counts once.
  • __deviceId: the visitor's device ID, from pieowl.getDeviceId() in the browser. The purchase is credited to their visit.

For a refund, send the same event with __refund set to true. Leave out __amount to refund the whole order. See Revenue attribution.

python
pieowl_send("track", {
    "name": "revenue",
    "properties": {
        "__amount": 49.99,
        "__currency": "EUR",
        "__orderId": "A-1001",
        "__deviceId": device_id,
    },
})

# Refund the whole order
pieowl_send("track", {
    "name": "revenue",
    "properties": {"__orderId": "A-1001", "__refund": True},
})

Good to know

  • Errors: urlopen raises urllib.error.HTTPError when Pieowl rejects a request, for example a bad client secret or an invalid payload. Catch it so analytics never breaks a user request.
  • Don't block requests: In a web app, send events from a background thread or task queue.
  • More event types: Groups and the full request schema are in the Track API reference.