如何在Fathom Analytics API调用中添加路径过滤？

问题背景 #

尝试调用Fathom Analytics API获取报表时，需要按特定pathname过滤数据，但不清楚如何在curl请求中加入过滤逻辑，同时Python代码携带过滤参数时调用失败，移除参数则正常。

一、Curl调用添加过滤条件的正确方式 #

Fathom Analytics API的GET请求支持两种传递过滤参数的方式，推荐使用第一种：

方式1：通过URL查询参数传递（更兼容） #

将过滤规则转为URL编码的JSON字符串，作为filter参数附加在请求URL后：

curl --location --request GET 'https://api.usefathom.com/v1/aggregations?entity=pageview&entity_id=[SITE_ID_HERE]&aggregates=visits,uniques,pageviews,avg_duration,bounce_rate&filter=%5B%7B%22property%22%3A%22pathname%22%2C%22operator%22%3A%22is%22%2C%22value%22%3A%22%2Fyour-target-path%22%7D%5D' \
--header 'Authorization: Bearer [BEARER_TOKEN_HERE]'

说明：%5B%7B%22property%22%3A...%5D是过滤规则[{"property":"pathname","operator":"is","value":"/your-target-path"}]的URL编码结果，可通过在线工具自行编码自定义规则

方式2：GET请求携带JSON请求体 #

部分服务器支持GET请求带请求体，需显式设置Content-Type：

curl --location --request GET 'https://api.usefathom.com/v1/aggregations?entity=pageview&entity_id=[SITE_ID_HERE]&aggregates=visits,uniques,pageviews,avg_duration,bounce_rate' \
--header 'Authorization: Bearer [BEARER_TOKEN_HERE]' \
--header 'Content-Type: application/json' \
--data-raw '[
    {"property": "pathname", "operator": "is", "value": "/your-target-path"}
]'

二、Python代码修复方案 #

你的Python调用失败原因是GET请求通常不允许携带JSON请求体，服务器会拒绝此类请求。正确做法是将过滤规则转为JSON字符串，作为filter查询参数传递：

import requests
import json

endpoint = "https://api.usefathom.com/v1/aggregations"
# 统一构造所有查询参数
params = {
    "entity": "pageview",
    "entity_id": "[SITE_ID]",
    "aggregates": "pageviews,visits,uniques,avg_duration,bounce_rate",
    "date_from": "2022-10-01",
    "date_to": "2022-10-31",
    # 将过滤规则转为JSON字符串作为参数值
    "filter": json.dumps([{"property": "pathname", "operator": "is", "value": "/[URL TO FILTER]"}])
}
headers = {
    "Authorization": "Bearer [BEARER_TOKEN]"
}

response = requests.get(endpoint, params=params, headers=headers)
print(response.json())

注意事项 #

• 替换代码中的[SITE_ID]、[BEARER_TOKEN]、/[URL TO FILTER]为真实业务值
• 过滤规则的operator支持contains、not is等多种选项，可根据需求调整

内容的提问来源于stack exchange，提问作者paperclip