import os
from datetime import date, timedelta
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>"
ASSET_NAME = "<your-asset-name>"
METRIC = "visibility_score" # or share_of_voice, average_position, ...
DAYS = 7
INCLUSIVE_END = date(2026, 5, 11) # the last day of your current window
def get_visibility_score(category_id, asset_name, metric, start, end):
"""Aggregate score for one asset in one window."""
res = client.reports.visibility(
category_id=category_id,
start_date=start.isoformat(),
end_date=end.isoformat(),
metrics=[metric],
filters=[{"field": "asset_name", "operator": "is", "value": asset_name}],
)
order = res.info.query["metrics"]
return res.data[0].metrics[order.index(metric)]
def current_and_prior_windows(inclusive_end, days):
"""Two (start, end_exclusive) pairs of equal length, back-to-back."""
current = (
inclusive_end - timedelta(days=days - 1),
inclusive_end + timedelta(days=1), # +1 day → exclusive end
)
prior = (current[0] - timedelta(days=days), current[0])
return current, prior
# Helpers — translate human-readable names into the IDs the report API needs.
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}")
def find_asset_name(category_id, name):
"""Return the canonical asset name (case-insensitive) inside the category."""
for a in client.organizations.categories.assets(category_id):
if a.name.lower() == name.lower():
return a.name
raise ValueError(f"No asset named {name!r} in this category")
# Resolve names → IDs, then run both windows.
category_id = find_category_id(CATEGORY_NAME)
asset_name = find_asset_name(category_id, ASSET_NAME)
current, prior = current_and_prior_windows(INCLUSIVE_END, DAYS)
current_score = get_visibility_score(category_id, asset_name, METRIC, *current)
prior_score = get_visibility_score(category_id, asset_name, METRIC, *prior)
delta_pp = (current_score - prior_score) * 100
print(f"{asset_name} {METRIC}: {current_score:.1%} ({delta_pp:+.1f} pp vs prev period)")
