Mo Elzubeir
104 lines
3.1 KiB
Markdown
104 lines
3.1 KiB
Markdown
# Socialhose SDKs
|
|
|
|
Official SDKs for the Socialhose Public API.
|
|
|
|
Socialhose is a social-listening and media-monitoring API for turning large streams of public mentions into usable campaign intelligence. It helps applications answer questions like:
|
|
|
|
- What are people saying about a campaign, brand, organization, product, policy, person, or event?
|
|
- Which platforms are driving the conversation?
|
|
- Is sentiment improving or deteriorating?
|
|
- Which mentions have the most reach or engagement?
|
|
- Which keywords, topics, or entities are trending?
|
|
- Who should receive alerts or mailing-list updates?
|
|
|
|
## What you can build
|
|
|
|
Use Socialhose SDKs to build:
|
|
|
|
- Social-listening dashboards for campaigns, topics, brands, people, organizations, or locations.
|
|
- Monitoring tools that search public mentions across supported platforms.
|
|
- Analytics views showing volume, reach, engagement, sentiment, platform mix, and growth.
|
|
- Trend and keyword reports.
|
|
- High-impact mention feeds ordered by recency or engagement.
|
|
- Entity pages that summarize one term/person/company/topic using mention-search facets.
|
|
- Alerting and mailing-list workflows backed by Socialhose mailing lists.
|
|
- Batch jobs, CLI scripts, or serverless functions that pull Socialhose data into another system.
|
|
|
|
## API access
|
|
|
|
API access is available with paid Socialhose subscriptions. See [Socialhose pricing](https://socialhose.net/pricing) for current plans, or use a publicly provided API key if Socialhose offers one from time to time.
|
|
|
|
API keys are provisioned by Socialhose or your account administrator. The SDKs consume existing keys; they do not create, rotate, or manage keys.
|
|
|
|
Keep API keys server-side. Do not commit keys, expose them in frontend bundles, or send them to browsers. For browser applications, call Socialhose from your own backend and return only the data your frontend needs.
|
|
|
|
## SDKs
|
|
|
|
- `sdks/javascript` — npm package `@socialhose/api`
|
|
|
|
Future SDKs can live beside it, e.g. `sdks/python`, `sdks/go`, or `sdks/php`.
|
|
|
|
## JavaScript / TypeScript
|
|
|
|
Set the key server-side before using the SDK:
|
|
|
|
```bash
|
|
export SOCIALHOSE_API_KEY="sh_your_key_here"
|
|
```
|
|
|
|
```bash
|
|
npm install @socialhose/api
|
|
```
|
|
|
|
```ts
|
|
import { SocialhoseClient } from '@socialhose/api';
|
|
|
|
const socialhose = new SocialhoseClient({
|
|
apiKey: process.env.SOCIALHOSE_API_KEY!,
|
|
});
|
|
|
|
const mentions = await socialhose.getMentions({
|
|
content_search: 'hospital',
|
|
ordering: '-published_at',
|
|
});
|
|
|
|
console.log(mentions.count);
|
|
```
|
|
|
|
Documentation lives with the package:
|
|
|
|
- [Quick README](./sdks/javascript/README.md)
|
|
- [Usage guide](./sdks/javascript/docs/GUIDE.md)
|
|
- [API reference](./sdks/javascript/docs/API.md)
|
|
- [Entity analytics](./sdks/javascript/docs/ENTITY_ANALYTICS.md)
|
|
- [Caching and retries](./sdks/javascript/docs/CACHING_AND_RETRIES.md)
|
|
- [Examples](./sdks/javascript/examples)
|
|
|
|
## Development
|
|
|
|
Use pnpm 9.x.
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm test
|
|
pnpm typecheck
|
|
pnpm build
|
|
```
|
|
|
|
On machines where Corepack's pnpm shim is broken, use:
|
|
|
|
```bash
|
|
npx --yes pnpm@9.15.0 install
|
|
npx --yes pnpm@9.15.0 test
|
|
```
|
|
|
|
## Publishing JavaScript SDK
|
|
|
|
```bash
|
|
cd sdks/javascript
|
|
pnpm test
|
|
pnpm typecheck
|
|
pnpm build
|
|
npm publish --access public --provenance
|
|
```
|