Use it from backend TypeScript/JavaScript to fetch campaigns, analytics, mentions, mailing lists, and SDK-composed entity analytics with authentication, retries, timeouts, and caching handled consistently.

Install

npm install @socialhose/api

Node 18+ is required because the SDK uses built-in fetch, Response, and AbortSignal.timeout. You can pass a custom fetch implementation if needed.

Quickstart

import { SocialhoseClient } from '@socialhose/api';

const socialhose = new SocialhoseClient({
  apiKey: process.env.SOCIALHOSE_API_KEY!,
});

const mentions = await socialhose.getMentions({
  content_search: 'hospital',
  platforms: 'twitter',
  ordering: '-published_at',
});

console.log(mentions.count, mentions.results[0]?.content);

Documentation

Usage guide — what the SDK is, setup, common workflows, operational guidance.
API reference — every public class, function, method, option, and exported type.
Entity analytics — how term-level analytics are built, accuracy safeguards, rate-limit guidance.
Caching and retries — cache contract, retry policy, failure semantics.
Examples — runnable TypeScript examples.

Configuration

const socialhose = new SocialhoseClient({
  apiKey: process.env.SOCIALHOSE_API_KEY!,
  baseUrl: 'https://socialhose.net/api/public/v1',
  timeoutMs: 8_000,
  retries: 3,
  cacheTtlMs: 60_000,
});

The SDK sends Authorization: Api-Key <key> and a browser-like User-Agent by default. The user-agent is intentional: the current Socialhose API edge rejects some non-browser requests.

Main capabilities

Campaign discovery: getCampaigns(), getCampaign(id), getCampaignIdByMatch(match).
Analytics: getOverview(), getTimeline(), getSentiment(), getShareOfVoice(), getPlatforms(), getTopKeywords(), getTrending(), getTopMentions().
Mentions: getMentions() with campaign, date, platform, sentiment, text search, pagination, and ordering filters.
Mailing lists: getMailingLists(), inviteMailingListMember().
Entity analytics: getEntityBrief(), getEntityStats(), getEntityBriefs().
Low-level access: get(path, params), post(path, body).
Caching: built-in MemoryCache, disabling via NoopCache, or any custom Cache implementation.

Entity analytics warning

Entity analytics fan out multiple /mentions/ requests per term. Use cacheTtlMs, revalidateSeconds, or a persistent shared cache to stay under the approximate 60 req/min API-key rate limit.

const stats = await socialhose.getEntityStats('RSF', 'campaign-id', {
  revalidateSeconds: 900,
});

Errors

Failed requests throw SocialhoseError with status, path, body, and cause when available.

import { SocialhoseError } from '@socialhose/api';

try {
  await socialhose.getCampaign('missing');
} catch (error) {
  if (error instanceof SocialhoseError) {
    console.error(error.status, error.path, error.body);
  }
}

Development

pnpm install
pnpm test
pnpm typecheck
pnpm build

Publishing:

npm publish --access public --provenance