import os
from profound import Profound
client = Profound(api_key=os.environ["PROFOUND_API_KEY"])
# What to fetch — replace with your own values.
CATEGORY_NAME = "<your-category-name>"
START_DATE = "2026-05-05"
END_DATE = "2026-05-12" # exclusive — returns data through 2026-05-11
METRIC = "visibility_score" # or share_of_voice, average_position, ...
TOP_N = 10
def get_leaderboard(category_id, metric, start_date, end_date):
"""All assets in the category ranked by the chosen metric."""
res = client.reports.visibility(
category_id=category_id,
start_date=start_date,
end_date=end_date,
metrics=[metric],
dimensions=["asset_name"],
pagination={"limit": 50000, "offset": 0},
)
m_order = res.info.query["metrics"]
d_order = res.info.query["dimensions"]
i_metric = m_order.index(metric)
i_asset = d_order.index("asset_name")
# Lower-is-better for average_position; higher-is-better for everything else.
reverse = metric != "average_position"
return sorted(
[(row.dimensions[i_asset], row.metrics[i_metric]) for row in res.data],
key=lambda x: x[1],
reverse=reverse,
)
# Helper — translate the category name to the UUID the report API expects.
def find_category_id(name):
"""Return the UUID of the category whose name matches (case-insensitive)."""
for c in client.organizations.categories.list():
if c.name.lower() == name.lower():
return c.id
raise ValueError(f"No category named {name!r}")
# Resolve name → ID, then run.
category_id = find_category_id(CATEGORY_NAME)
leaderboard = get_leaderboard(category_id, METRIC, START_DATE, END_DATE)
for rank, (name, value) in enumerate(leaderboard[:TOP_N], start=1):
print(f"{rank:>2}. {name:<24} {value:.1%}")
