Fathom Python SDK

0.0.37 verified Sat May 09 auth: no python

Official Python SDK for Fathom Analytics, providing a simple interface to record page views, events, and goals via the Fathom API. Current version 0.0.37, actively maintained with irregular releases.

pip install fathom-python

Common errors

error AttributeError: module 'fathom' has no attribute 'FathomClient' ↓

cause Using 'import fathom' instead of 'from fathom import FathomClient'.

fix

Use 'from fathom import FathomClient'.

error TypeError: __init__() missing 2 required positional arguments: 'api_token' and 'site_id' ↓

cause Creating FathomClient without required arguments.

fix

client = FathomClient(api_token='...', site_id='...')

error fathom.exceptions.FathomHTTPError: 401 Unauthorized ↓

cause Invalid or expired API token.

fix

Generate a new API token in your Fathom dashboard and update your code.

error requests.exceptions.ConnectionError: HTTPSConnectionPool ... Max retries exceeded ↓

cause Network connectivity issue or Fathom API is down. The SDK does not retry automatically.

fix

Add retry logic (e.g., with requests.adapters.HTTPAdapter(max_retries=3)).

Warnings

breaking In version 0.0.30 the 'pageview' method signature changed: 'hostname' parameter was removed and 'url' is now required to be a full URL including protocol. Older versions expected just a path. ↓

fix Always provide the full URL (e.g., 'https://example.com/page').

deprecated The 'event' method is deprecated since 0.0.35. Use 'goal' instead for recording custom goals. ↓

fix Replace client.event(name=..., url=...) with client.goal(goal_id=..., url=...).

gotcha The library does not automatically retry on rate limits or network errors. You must wrap calls in your own retry logic. ↓

fix Use requests.Session with retries or a library like tenacity.

Imports

FathomClient
wrong
```
from fathom_python import FathomClient
```
correct
```
from fathom import FathomClient
```
The package installs as 'fathom', not 'fathom_python'.
FathomClient
wrong
```
import fathom
```
correct
```
from fathom import FathomClient
```
Direct import of the module gives you the module object, not the class.

Quickstart

Initialize the client with your API token and site ID, then record a page view.

from fathom import FathomClient

client = FathomClient(
    api_token=os.environ.get('FATHOM_API_TOKEN', ''),
    site_id=os.environ.get('FATHOM_SITE_ID', '')
)

# Record a page view
response = client.pageview(
    url='https://example.com/page',
    referrer='https://example.com/other'
)
print(response)