docs: clarify API access and SDK docs
This commit is contained in:
Mo Elzubeir
@@ -2,6 +2,36 @@
|
||||
|
||||
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`
|
||||
@@ -10,7 +40,7 @@ Future SDKs can live beside it, e.g. `sdks/python`, `sdks/go`, or `sdks/php`.
|
||||
|
||||
## JavaScript / TypeScript
|
||||
|
||||
API keys are provisioned by Socialhose or your account administrator. Set the key server-side before using the SDK:
|
||||
Set the key server-side before using the SDK:
|
||||
|
||||
```bash
|
||||
export SOCIALHOSE_API_KEY="sh_your_key_here"
|
||||
|
||||
@@ -2,47 +2,24 @@
|
||||
|
||||
Official TypeScript SDK 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 backend 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?
|
||||
|
||||
The SDK wraps the Socialhose REST API with typed JavaScript/TypeScript methods for campaign discovery, analytics dashboards, mention search, mailing lists, and SDK-composed entity analytics. It handles API-key auth, browser-compatible headers, retries, timeouts, GET caching, and normalized response shapes so product code can focus on the analysis instead of raw HTTP plumbing.
|
||||
|
||||
## What you can build with it
|
||||
|
||||
Use `@socialhose/api` from server-side JavaScript/TypeScript 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.
|
||||
|
||||
This package is intended for **backend code only**. Do not ship your Socialhose API key to browsers.
|
||||
|
||||
## Getting an API key
|
||||
|
||||
API keys are issued by Socialhose. The SDK does not create keys, and there is no self-service key-generation flow documented in this package.
|
||||
See the repository [API access notes](../../README.md#api-access) for subscription and key-provisioning details. This package consumes an existing key; it does not create keys, and there is no self-service key-generation flow documented here.
|
||||
|
||||
To use the SDK:
|
||||
|
||||
1. Request Socialhose Public API access from the Socialhose team or your account administrator.
|
||||
2. Ask for an API key with access to the campaigns you need to query.
|
||||
3. Store it as a server-side environment variable:
|
||||
1. Get a Socialhose API key with access to the campaigns you need to query.
|
||||
2. Store it as a server-side environment variable:
|
||||
|
||||
```bash
|
||||
export SOCIALHOSE_API_KEY="sh_your_key_here"
|
||||
```
|
||||
|
||||
4. Pass it to the client:
|
||||
3. Pass it to the client:
|
||||
|
||||
```ts
|
||||
const socialhose = new SocialhoseClient({
|
||||
|
||||
@@ -66,7 +66,7 @@ Type exports:
|
||||
|
||||
## Authentication
|
||||
|
||||
Socialhose API keys are provisioned by Socialhose or by your account administrator. This SDK consumes an existing key; it does not create or manage keys.
|
||||
See the repository [API access notes](../../../README.md#api-access) for subscription and key-provisioning details. This SDK consumes an existing key; it does not create or manage keys.
|
||||
|
||||
Every request sends:
|
||||
|
||||
|
||||
@@ -22,9 +22,9 @@ Requires Node 18+ or a custom `fetch` implementation.
|
||||
|
||||
## Getting API access
|
||||
|
||||
Socialhose API keys are provisioned by Socialhose. This SDK only consumes an existing key; it cannot create, rotate, or discover keys for you.
|
||||
See the repository [API access notes](../../../README.md#api-access) for subscription and key-provisioning details. This SDK only consumes an existing key; it cannot create, rotate, or discover keys for you.
|
||||
|
||||
Ask the Socialhose team or your account administrator for a Public API key and confirm which campaigns it can access. Then set it in your server environment:
|
||||
Use your provided Public API key and confirm which campaigns it can access. Then set it in your server environment:
|
||||
|
||||
```bash
|
||||
export SOCIALHOSE_API_KEY="sh_your_key_here"
|
||||
|
||||
Reference in New Issue
Block a user