@socialhose/api

TypeScript SDK for the Socialhose Public API.

Install

npm install @socialhose/api

Node 18+ is required because the SDK uses the built-in fetch, Response, and AbortSignal.timeout APIs. 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);

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.

Endpoints

getCampaigns()
getCampaign(id)
getOverview(filters)
getTimeline(filters)
getSentiment(filters)
getShareOfVoice(filters)
getPlatforms(filters)
getTopKeywords(filters)
getTrending(filters)
getTopMentions(filters)
getMentions(filters)
getMailingLists()
inviteMailingListMember(listId, invite)
get(path, params) for lower-level GET access
post(path, body) for lower-level POST access

Filtering examples

await socialhose.getOverview({
  campaign_ids: 'campaign-id',
  date_from: '2026-05-01',
  date_to: '2026-05-29',
  platforms: 'twitter,reddit',
  sentiments: 'negative',
});

await socialhose.getTimeline({
  campaign_ids: 'campaign-id',
  interval: 'day',
});

Next.js cache integration

Pass revalidateSeconds per request. In Next.js this is forwarded as fetch(..., { next: { revalidate } }); outside Next.js it is harmless.

await socialhose.getMentions({ content_search: 'ozempic' }, { revalidateSeconds: 3600 });

Errors

Failed requests throw SocialhoseError with status, path, and response body 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);
  }
}

Publishing

pnpm test
pnpm typecheck
pnpm build
npm publish --access public --provenance

2.5 KiB Raw Blame History