PHP SDK

earlyforge/pulse-sdk is a zero-dependency PHP 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.

It uses ext-curl directly rather than pulling in an HTTP client library for 4 GET endpoints.

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

Install

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

git clone https://github.com/earlyforge/earlyforge.git
composer config repositories.earlyforge-pulse-sdk path earlyforge/tools/sdk-php-earlyforge
composer require earlyforge/pulse-sdk:@dev

A published composer require earlyforge/pulse-sdk package is coming.

Quickstart

use EarlyForge\Pulse\PulseClient;
 
$client = new PulseClient('ef_live_xxxxxxxxxxxxxxxx');
 
$snapshot = $client->topTrends(null, 'fr');
echo $snapshot['trends'][0]['display_name'];

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

Methods

new PulseClient(string $apiKey, string $baseUrl = 'https://api.earlyforge.ai')

Constructs the client. Throws InvalidArgumentException if $apiKey is empty.

topTrends(?string $date = null, ?string $locale = null): array

Global top trends — same daily snapshot as the Pulse homepage. Returns ['trends' => [...], 'total' => int, 'cached_at' => string, 'cache_ttl_seconds' => int].

trendsByRegion(string $region, ?string $date = null, ?string $locale = null): array

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

trendsByCategory(string $category, ?string $date = null, ?string $locale = null): array

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

getTrend(string $trendId): array

Detail for one trend. Same fields as a trend entry, plus canonical_name, sources, a full description, and a timeline of {ts, score, sources_count} points.

Error handling

Every non-2xx response throws EarlyForge\Pulse\PulseApiException with getStatusCode() and getDetail() — mirroring the OpenAPI contract's 401 (missing/invalid/revoked key), 404 (unknown trend), and 502 (upstream unavailable) responses. Network/cURL failures also throw PulseApiException.

use EarlyForge\Pulse\PulseApiException;
 
try {
    $client->getTrend('does-not-exist');
} catch (PulseApiException $e) {
    echo $e->getStatusCode() . ': ' . $e->getDetail();
}

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.