Amplitude Python SDK

Warnings

• breaking Major version updates (e.g., v1.x to v2.x) may introduce significant changes to public interfaces, behaviors, or semantics. Always review upgrade guidelines carefully when moving to a new major version.
  Fix: Consult the official Amplitude documentation and release notes for specific migration guides and breaking changes when updating to a new major version.
• gotcha Events are queued in memory and sent in batches. If your application exits immediately after calling `track()`, events might not be sent. You must call `client.flush()` to ensure all buffered events are delivered.
  Fix: Explicitly call `amplitude.flush()` before your application terminates, especially in short-lived scripts or serverless functions. You can also configure `flush_queue_size` and `flush_interval_millis` for batching behavior.
• gotcha By default, data is sent to Amplitude's US servers. If your project requires EU data residency, you must explicitly configure the `server_zone` to 'EU' during SDK initialization.
  Fix: Initialize the SDK with `amplitude = Amplitude(API_KEY, configuration={'server_zone': 'EU'})` or set it via `amplitude.configuration.server_zone = 'EU'` after initialization.
• gotcha Using an incorrect API key or having multiple SDK instances (e.g., different Amplitude projects within the same application) without proper separation can lead to events not being ingested or being sent to the wrong project.
  Fix: Verify that the correct API key is used during `Amplitude` client initialization. If using multiple instances, ensure each is configured with its specific API key and managed distinctly.
• gotcha Amplitude has a minimum length requirement for `user_id` and `device_id`. Providing IDs shorter than this minimum can result in 400 errors and events not being tracked.
  Fix: Ensure that `user_id` and `device_id` values meet the minimum length requirements (typically 5 characters, configurable via `min_id_length`).
• gotcha Amplitude enforces a throttling limit of 30 events per user or device per second. Exceeding this limit can cause events to be throttled and logged with a warning, leading to incomplete data.
  Fix: Distribute your event tracking across time or reduce the frequency of event calls for individual users/devices to stay within the throttling limit.

Install

• pip install amplitude-analytics Install stable version

Imports

• Amplitude

  from amplitude import Amplitude

• BaseEvent

  from amplitude import BaseEvent

• Identify

  from amplitude import Identify

Quickstart

Initializes the Amplitude SDK with an API key (preferably from environment variables), tracks a custom event, and sets user properties. It emphasizes the importance of calling `flush()` to ensure events are sent before the application terminates, and shows how to configure for EU data residency.

import os
from amplitude import Amplitude, BaseEvent, Identify
import time

AMPLITUDE_API_KEY = os.environ.get("AMPLITUDE_API_KEY", "YOUR_AMPLITUDE_API_KEY")

# Initialize the SDK
# For EU data residency, add: server_zone='EU' to Amplitude(API_KEY, ...)
amplitude = Amplitude(AMPLITUDE_API_KEY)

# Example: Configure for EU data residency (uncomment if applicable)
# amplitude.configuration.server_zone = 'EU'

# Create and track a basic event
print("Tracking a 'User Logged In' event...")
event = BaseEvent(
    event_type="User Logged In",
    user_id="user_123",
    device_id="device_abc",
    event_properties={
        "login_method": "email",
        "timestamp": int(time.time())
    }
)
amplitude.track(event)

# Identify a user and set/update user properties
print("Setting user properties for 'user_123'...")
identify = Identify()
identify.set("plan", "premium")
identify.set_once("initial_referrer", "google") # Set only once
identify.add("login_count", 1) # Increment a property
amplitude.identify("user_123", identify)

# Important: Flush events before application exit to ensure delivery
print("Flushing events...")
amplitude.flush()
print("Events sent and flushed. Check your Amplitude project.")