Usage

Usage

import trendflow
from trendflow import Region, Timeframe, Resolution, SearchProperty, ExportFormat

# Initialize client (optional API config)
tf = trendflow.Client(language="en", timeout=10)

# --- Enums for type safety ---
# Region.US, Region.GB, Region.DE ...             (or any code: "US-CA", "807")
# Timeframe.PAST_HOUR ... PAST_5_YEARS, ALL_TIME  (or "2023-01-01 2023-06-30")
# Resolution.COUNTRY, Resolution.REGION, Resolution.CITY
# SearchProperty.WEB, IMAGES, NEWS, YOUTUBE, SHOPPING

# Fetch interest over time
data = tf.interest_over_time(
    keywords=["Python", "JavaScript", "Rust"],
    timeframe=Timeframe.PAST_YEAR,
    region=Region.US,
)

# Dataclass-backed results
print(data.keywords)        # ["Python", "JavaScript", "Rust"]
print(data.granularity)     # "weekly"
print(data.points)          # list of TrendPoint(date, scores: dict)

# Get regional breakdown (region defaults to Region.US)
regional = tf.interest_by_region(
    keyword="Python",
    resolution=Resolution.COUNTRY,
)

# Trending searches right now
trending = tf.trending_now(region=Region.US)
for item in trending.results:
    print(item.title, item.traffic, item.articles)  # TrendingItem dataclass

# Related queries — returns RelatedResult dataclass (region defaults to worldwide)
related = tf.related_queries("machine learning", region=Region.GB)
for query in related.top:
    print(query.term, query.value)    # RelatedQuery(term, value)
for query in related.rising:
    print(query.term, query.breakout) # RelatedQuery(term, breakout%)

# --- Narrowing a query ---
# Every query method takes an optional category and search property, and any of them
# accepts a custom date range and a sub-region or metro code in place of the named values.

# "jaguar" the car, on YouTube, in California, over the first half of 2023
jaguar = tf.interest_over_time(
    keywords=["jaguar"],
    timeframe="2023-01-01 2023-06-30",
    region="US-CA",
    category=47,  # Autos & Vehicles — disambiguates without needing a topic id
    search_property=SearchProperty.YOUTUBE,
)

# --- Exports ---
data.export(ExportFormat.CSV,  path="trends.csv")
data.export(ExportFormat.JSON, path="trends.json")
data.to_dataframe()  # pandas DataFrame