Python SDK

earlyforge is a thin, synchronous Python client for the Pulse API — the same free, authenticated daily snapshot documented on that page. It wraps the 4 Pulse endpoints only; it is not a client for EarlyForge's paid real-time Trends detection catalog, articles, briefs, or alerts APIs.

Source: tools/sdk-python-earlyforge — read the package's own README for anything not covered here.

Install

Not published to PyPI yet — install from a clone of the repository:

git clone https://github.com/earlyforge/earlyforge.git
pip install -e earlyforge/tools/sdk-python-earlyforge

A published pip install earlyforge package is coming.

Quickstart

from earlyforge import PulseClient
 
client = PulseClient(api_key="ef_live_xxxxxxxxxxxxxxxx")
 
snapshot = client.top_trends(locale="fr")
print(snapshot["trends"][0]["display_name"])

Get a key from Settings → API Keys in the console — any account works, Pulse access is free.

Methods

PulseClient(api_key, base_url="https://api.earlyforge.ai", *, timeout=15.0)

Constructs the client. Raises ValueError if api_key is empty.

top_trends(*, date=None, locale=None)

Global top trends — same daily snapshot as the Pulse homepage.

• date — pick a past daily snapshot (YYYY-MM-DD). Omit for the latest.
• locale — locale for translated fields, e.g. "fr".

Returns {"trends": [...], "total": int, "cached_at": str, "cache_ttl_seconds": int}.

trends_by_region(region, *, date=None, locale=None)

Top trends for an ISO 3166-1 alpha-2 region code (e.g. "US", "FR"). Same response shape as top_trends.

trends_by_category(category, *, date=None, locale=None)

Top trends for a category (e.g. "politics", "tech"). Same response shape as top_trends.

get_trend(trend_id)

Detail for one trend (from a trend_id returned by top_trends). Same fields as a trend entry, plus canonical_name, sources, a full description, and a timeline of {ts, score, sources_count} points.

client.get_trend("tr_a1b2c3")

Error handling

Every non-2xx response raises earlyforge.PulseApiError with status_code and detail attributes — mirroring the OpenAPI contract's 401 (missing/invalid/revoked key), 404 (unknown trend), and 502 (upstream unavailable) responses. Network failures (DNS, timeout, connection refused) also raise PulseApiError.

from earlyforge import PulseApiError
 
try:
    client.get_trend("does-not-exist")
except PulseApiError as exc:
    print(exc.status_code, exc.detail)

Rate limits

No monthly call quota on this surface, for any plan — only the shared 60 requests/60 seconds burst limit applies, same as the anonymous Pulse page.

Going further

This SDK only covers the free Pulse snapshot — it's the entire public API, on every plan. EarlyForge's paid plans add real-time trend detection across the full catalog of countries and categories inside the app itself (console only, not via this SDK) — see the pricing page for that upgrade path.