Twitter Analytics Report Template: 9 Sections, Filled In From the API

# Monthly Twitter (X) analytics report: fills the 9-section template for one
# account plus competitors, writes report_<handle>_<YYYY-MM>.md and a per-post CSV
import os, csv, statistics, requests
from collections import Counter
from datetime import datetime, timezone

API = "https://api.twitterapi.io"
HEADERS = {"X-API-Key": os.environ["TWITTERAPI_IO_KEY"]}
HANDLE = "nasa"
COMPETITORS = ["esa", "spacex"]
YEAR, MONTH = 2026, 9

def get(path, **params):
    r = requests.get(API + path, headers=HEADERS, params=params, timeout=20)
    r.raise_for_status()
    return r.json()

def month_bounds(y, m):
    lo = datetime(y, m, 1, tzinfo=timezone.utc)
    hi = datetime(y + (m == 12), m % 12 + 1, 1, tzinfo=timezone.utc)
    return int(lo.timestamp()), int(hi.timestamp())

def parse_ts(s):  # "Tue Dec 10 07:00:30 +0000 2024"
    return datetime.strptime(s, "%a %b %d %H:%M:%S %z %Y")

def engagements(t):
    return sum(t.get(k) or 0 for k in ("likeCount", "retweetCount", "replyCount", "quoteCount"))

def month_posts(handle, y, m):
    lo, hi = month_bounds(y, m)
    query = f"from:{handle} since_time:{lo} until_time:{hi}"
    cursor, out = "", []
    while True:
        body = get("/twitter/tweet/advanced_search", query=query, queryType="Latest", cursor=cursor)
        out += [t for t in body.get("tweets", []) if not t.get("retweeted_tweet")]
        if not body.get("has_next_page"):
            return out
        cursor = body["next_cursor"]

def follower_delta(handle, now):
    # user/info only returns today's count, so keep your own monthly snapshots
    path, prev = f"followers_{handle}.csv", None
    if os.path.exists(path):
        with open(path) as f:
            rows = list(csv.reader(f))
        prev = int(rows[-1][1]) if rows else None
    with open(path, "a", newline="") as f:
        csv.writer(f).writerow([datetime.now(timezone.utc).date().isoformat(), now])
    return None if prev is None else now - prev

def summarize(handle, y, m):
    profile = get("/twitter/user/info", userName=handle)["data"]
    tweets = month_posts(handle, y, m)
    views = [t.get("viewCount") or 0 for t in tweets]
    total_eng = sum(engagements(t) for t in tweets)
    return {
        "handle": handle,
        "followers": profile.get("followers") or 0,
        "posts": sum(1 for t in tweets if not t.get("isReply")),
        "replies_sent": sum(1 for t in tweets if t.get("isReply")),
        "views": sum(views),
        "median_views": int(statistics.median(views)) if views else 0,
        "likes": sum(t.get("likeCount") or 0 for t in tweets),
        "reposts": sum(t.get("retweetCount") or 0 for t in tweets),
        "replies": sum(t.get("replyCount") or 0 for t in tweets),
        "quotes": sum(t.get("quoteCount") or 0 for t in tweets),
        "bookmarks": sum(t.get("bookmarkCount") or 0 for t in tweets),
        "eng_rate": round(100 * total_eng / sum(views), 2) if sum(views) else None,
        "tweets": tweets,
    }

def top(counter, n=5):
    return ", ".join(f"{k} ({v})" for k, v in counter.most_common(n)) or "none"

def render(me, rivals, delta, y, m):
    tw = me["tweets"]
    best = sorted(tw, key=engagements, reverse=True)[:5]
    days = Counter(parse_ts(t["createdAt"]).strftime("%a") for t in tw)
    hours = Counter(f"{parse_ts(t['createdAt']).hour:02d}:00 UTC" for t in tw)
    ents = [t.get("entities") or {} for t in tw]
    tags = Counter("#" + h["text"].lower() for e in ents for h in e.get("hashtags") or [])
    ments = Counter("@" + u["screen_name"].lower() for e in ents for u in e.get("user_mentions") or [])
    clients = Counter(t.get("source") or "unknown" for t in tw)
    growth = "first snapshot" if delta is None else f"{delta:+,} since last snapshot"
    lines = [
        f"# X analytics report: @{me['handle']}, {y}-{m:02d}", "",
        "## 1. Summary", "_Write 2-3 sentences after reading sections 2-8._", "",
        "## 2. Audience", f"- Followers: {me['followers']:,} ({growth})", "",
        "## 3. Output", f"- Posts: {me['posts']}  |  Replies sent: {me['replies_sent']}", "",
        "## 4. Reach", f"- Views: {me['views']:,}  |  Median views per post: {me['median_views']:,}", "",
        "## 5. Engagement",
        f"- Likes {me['likes']:,} · Reposts {me['reposts']:,} · Replies {me['replies']:,} · "
        f"Quotes {me['quotes']:,} · Bookmarks {me['bookmarks']:,}",
        f"- Engagement rate by views: {me['eng_rate']}%", "",
        "## 6. Top 5 posts", *[f"- {engagements(t):,} engagements · {t.get('url')}" for t in best], "",
        "## 7. Cadence and content mix",
        f"- Busiest days: {top(days, 3)}", f"- Busiest hours: {top(hours, 3)}",
        f"- Hashtags: {top(tags)}", f"- Mentions: {top(ments)}", f"- Posting clients: {top(clients, 3)}", "",
        "## 8. Competitor benchmark",
        "| Account | Followers | Posts | Median views | Eng. rate (views) |", "| --- | --- | --- | --- | --- |",
        *[f"| @{r['handle']} | {r['followers']:,} | {r['posts']} | {r['median_views']:,} | {r['eng_rate']}% |"
          for r in [me, *rivals]], "",
        "## 9. Next month", "_Two or three actions, each tied to a number above._",
    ]
    return "\n".join(lines)

me = summarize(HANDLE, YEAR, MONTH)
rivals = [summarize(h, YEAR, MONTH) for h in COMPETITORS]
delta = follower_delta(HANDLE, me["followers"])
stem = f"report_{HANDLE}_{YEAR}-{MONTH:02d}"
with open(stem + ".md", "w") as f:
    f.write(render(me, rivals, delta, YEAR, MONTH))
with open(stem + ".csv", "w", newline="") as f:
    w = csv.writer(f)
    w.writerow(["id", "createdAt", "isReply", "views", "likes", "reposts", "replies", "quotes", "bookmarks", "url"])
    for t in me["tweets"]:
        w.writerow([t["id"], t["createdAt"], t.get("isReply"), t.get("viewCount"), t.get("likeCount"),
                    t.get("retweetCount"), t.get("replyCount"), t.get("quoteCount"), t.get("bookmarkCount"), t.get("url")])
n = len(me["tweets"]) + sum(len(r["tweets"]) for r in rivals)
print(f"wrote {stem}.md/.csv from {n} posts, approx cost ${n * 0.00015 + (1 + len(COMPETITORS)) * 0.00018:.3f}")