# NicheIQs — AI-Powered Market Niche Scoring

> Score any market niche 0–100 for winnability before building. Real scraped signals — not LLM brainstorming.

## What NicheIQs Does

NicheIQs is a market research API that scores business niches on a 0–100 Winnability Scale. It is designed for autonomous agents, AI-powered research pipelines, and indie founders evaluating markets to enter.

Given any niche (e.g. "AI invoice software for freelancers", "dog anxiety supplements", "remote bookkeeping for Shopify stores"), NicheIQs returns a structured report containing:

- A **Winnability Score** (0–100)
- A **verdict**: STRONG (≥70), VIABLE (50–69), WEAK (<50), or CROWDED
- A **breakdown** across four dimensions: pain signal, demand, competition, monetization
- **Recommendations**: 3–5 concrete next steps
- **Agent hints**: a structured decision block with `should_proceed` (boolean), `icp`, `biggest_risk`, `monetization`, `next_step`
- **Related niches**: 3 adjacent niches worth scoring next
- **Key subreddits**: where the target audience is most active

## Data Sources

Every score is derived from real, scraped signals — not Claude's training knowledge:

- **Reddit** — pain volume, complaint frequency, and urgency across relevant subreddits
- **Google Trends** — 12-month demand curve, geo breakdown (US, GB, IN, AU, BR), YouTube interest
- **ProductHunt** — product count and competition density in the space
- **Claude AI synthesis** — Riley, a senior market analyst persona, synthesizes signals using Jobs-to-be-Done, Porter's Five Forces, and Crossing the Chasm frameworks

## For Autonomous Agents

NicheIQs is built agent-first. Key properties:

- **Synchronous endpoint** (`POST /analyze/sync`) — one call, one result, no polling loop required
- **Batch endpoint** (`POST /analyze/batch`) — score up to 10 niches in parallel, with optional webhook callback
- **`agent_hints.should_proceed`** — binary go/no-go boolean for automated decision gates
- **`related_niches`** — enables autonomous chaining without human input
- **Webhook callbacks** — post results to any URL when analysis completes
- **Bearer token auth** — works with `Authorization: Bearer <key>` in addition to `X-API-Key`
- **OpenAPI spec** — machine-readable at `https://nicheiqs.com/oauth/chatgpt_openapi.yaml`

### Recommended Agent Pattern

```
1. POST /analyze/sync {"niche": "<niche>", "client": "<agent-id>"}
2. Check report.agent_hints.should_proceed
3. If true: proceed to next stage with report.agent_hints as context
4. If false: try report.related_niches[0] or reject and move on
```

### Batch Pattern (parallel scoring)

```
POST /analyze/batch
{
  "niches": ["niche A", "niche B", "niche C"],
  "callback_url": "https://your-agent/webhook",
  "client": "your-agent-id"
}
```

Returns job_ids immediately. Fires callback_url with all results when complete.

## API Reference

**Base URL**: `https://nicheiqs.com`

**Authentication**: `X-API-Key: <key>` header or `Authorization: Bearer <key>`

**Get a key**: `https://nicheiqs.com` — free tier includes 3 analyses. PAYG is $0.10/analysis with no monthly commitment.

### Endpoints

#### POST /analyze/sync
Synchronous analysis. Submit a niche, receive a full WinnabilityReport in one response (20–60s).

Request:
```json
{
  "niche": "AI invoice software for freelancers",
  "client": "your-agent-id"
}
```

Response:
```json
{
  "niche": "AI invoice software for freelancers",
  "score": 74,
  "verdict": "strong",
  "summary": "Strong pain signal from freelancers drowning in manual invoicing...",
  "breakdown": {
    "pain_score": 82,
    "demand_score": 71,
    "competition_score": 58,
    "monetization_score": 79
  },
  "recommendations": [
    "Start with a Stripe-connected MVP targeting designers on r/freelance",
    "..."
  ],
  "agent_hints": {
    "should_proceed": true,
    "icp": "Freelance designers and developers billing 3–10 clients/month",
    "biggest_risk": "FreshBooks and Wave already own this space at low price points",
    "monetization": "SaaS $19–29/month or % of invoiced revenue",
    "next_step": "Post in r/freelance asking about invoicing pain — validate before building"
  },
  "related_niches": [
    "AI contract generation for freelancers",
    "automated expense tracking for solopreneurs",
    "client onboarding software for agencies"
  ],
  "key_subreddits": ["freelance", "webdev", "graphic_design", "Entrepreneur"]
}
```

#### GET /usage
Returns current-month usage for the authenticated API key. Auth required — free-demo key not accepted.

Response:
```json
{
  "tier": "starter",
  "analyses_used_this_month": 12,
  "analyses_remaining": 18,
  "monthly_limit": 30,
  "reset_date": "2026-05-01T00:00:00+00:00",
  "is_payg": false
}
```

`analyses_remaining` and `monthly_limit` are null for payg (billed per use, no hard cap).
`is_payg: true` means there is no monthly cap — you are billed $0.10/analysis.

#### POST /analyze
Async analysis. Returns job_id immediately. Poll /results/{job_id} for completion.

#### GET /results/{job_id}
Poll for async job status. Returns `status: pending | started | success | failure` and full report on success.

#### POST /analyze/batch
Score 1–10 niches in parallel. Optional webhook callback when all complete.

#### GET /trending
Returns top 12 most-queried niches with scores. Useful for benchmarking and discovery.

### Gap Alternatives

When a niche scores below 60, the response includes up to 3 adjacent niches identified as potentially underserved. Each alternative is narrower than the original — a sub-niche or underserved segment, never a broader pivot.

Useful for autonomous agents that want to iterate from a weak score to a stronger one without re-prompting the user.

Each alternative includes:
- `niche` — the narrower niche name
- `why` — one sentence on why it's more defensible
- `gap_signal` — a concrete data point from scraped signals (e.g. ProductHunt count, Reddit thread count, Trends slope)
- `predicted_strength` — `"stronger"` or `"likely stronger"` relative to the original

Example: submit `"AI writing assistant"` (score 22, saturated — 40+ ProductHunt results) → response includes:
```json
{
  "alternatives": [
    {
      "niche": "AI writing assistant for technical grant applications",
      "why": "Grant writers need structured output with compliance constraints that generic tools ignore.",
      "gap_signal": "Only 1 ProductHunt result for 'grant writing software' vs 40+ for 'AI writing assistant'.",
      "predicted_strength": "stronger"
    }
  ]
}
```

Alternatives are free — they do not consume an additional analysis credit.
When score >= 60, `alternatives` is an empty array `[]`.

### Agent pattern for weak scores

```
1. POST /analyze/sync {"niche": "<niche>"}
2. If report.score < 60 AND report.alternatives is non-empty:
   a. Score each alternative: POST /analyze/sync {"niche": alt.niche}
   b. Filter by agent_hints.should_proceed == true
   c. Return the strongest viable sub-niche to the user
3. If score >= 60: proceed with report.agent_hints
```

### Webhooks

Any endpoint that accepts `callback_url` will POST to that URL when the job completes.

**Retry policy**: 3 attempts with exponential backoff — waits 2s, then 4s, then 8s between attempts.
Your endpoint must respond with any 2xx status within 10 seconds per attempt or the attempt is counted as failed.

**Webhook payload** (same for all endpoints):
```json
{
  "status": "ok",
  "cached": false,
  "report": { ... full WinnabilityReport ... }
}
```

`cached: true` means the result was served from the 24-hour analysis cache — no new scraping was done.

Endpoints that support `callback_url`:
- `POST /analyze` — per-job webhook, fired when a single analysis completes
- `POST /analyze/batch` — batch webhook, fired once when ALL jobs in the batch complete

### Intelligence Endpoints (Starter+ required)

These endpoints run deeper analysis on top of the core winnability score.

#### POST /competitors → GET /competitors/{job_id}
Scrapes ProductHunt and Reddit for existing competitors, tool mentions, and market gaps.
Returns: competitors list (name, url, pricing, traction), market_gap, differentiation_opportunities, agent_hints.

#### POST /icp → GET /icp/{job_id}
Scrapes Reddit for Ideal Customer Profile signals: job titles, company sizes, co-mentioned tools, verbatim quotes.
Returns: primary_icp, secondary_icp, verbatim_quotes, agent_hints (outreach_channel, messaging_angle, avoid_segment).

#### POST /keywords → GET /keywords/{job_id}
Pulls related and rising Google Trends queries for SEO and content strategy.
Returns: seed_keywords (with volume_tier, intent, difficulty), primary_keyword, content_angles, agent_hints.

#### POST /monetization → GET /monetization/{job_id}
Scores SaaS, marketplace, productized_service, info_product, api, and community monetization models for the niche.
Returns: models list with fit_score + reasoning, recommended_model, agent_hints (fastest_to_revenue, highest_ceiling, avoid_model).

All intelligence endpoints return a job_id immediately and are polled via GET /{endpoint}/{job_id}.
Results are cached 24 hours.

### Monitoring (Pro+ required)

#### POST /monitor
Register a niche for daily re-scoring. POST to webhook_url when score shifts by ≥ alert_threshold points.
Max 10 active monitors per API key.

Request: `{"niche": "...", "webhook_url": "https://...", "alert_threshold": 10}`

#### GET /monitor
List all active monitors for your API key.

#### DELETE /monitor/{monitor_id}
Deactivate a monitor.

### Industry Heatmap (all tiers)

#### GET /heatmap
Returns aggregated winnability data across 30 canonical industry buckets.
Free tier: bucket name, avg_score, niche_count, trend_direction.
Starter+: also includes top_niches (5 highest-scoring niches per bucket).

Available buckets: b2b_saas, developer_tools, fintech, hr_recruiting, legal_compliance,
sales_crm, marketing_adtech, analytics_bi, security_privacy, infrastructure_devops,
ai_ml_tools, ecommerce_retail, supply_chain, health_wellness, mental_health, fitness_sports,
edtech, creator_economy, real_estate_proptech, travel_hospitality, food_beverage, pet_care,
parenting_family, sustainability, nonprofit_social, professional_services, media_entertainment,
gaming, consumer_marketplace, other.

#### GET /heatmap/{bucket} (Starter+)
Detailed stats for one industry bucket including top 5 niches by score.

#### GET /classify/{niche_hash} (all tiers)
Returns the industry bucket assignment for a niche by SHA-256 hash.
Classification is automatically assigned after each POST /analyze call.
niche_hash = SHA-256 of the lowercased niche string.

### Tier Access Matrix

| Endpoint | Free | Starter | Pro | Agent |
|---|---|---|---|---|
| /usage | ✓ | ✓ | ✓ | ✓ |
| /analyze/sync | ✓ (3/mo) | ✓ (30/mo) | ✓ (150/mo) | ✓ (1500/mo) |
| /competitors, /icp, /keywords, /monetization | — | ✓ | ✓ | ✓ |
| /monitor | — | — | ✓ | ✓ |
| /heatmap (summary) | ✓ | ✓ | ✓ | ✓ |
| /heatmap (top_niches) | — | ✓ | ✓ | ✓ |
| /heatmap/{bucket} | — | ✓ | ✓ | ✓ |
| /classify/{hash} | ✓ | ✓ | ✓ | ✓ |

## Pricing

| Tier | Price | Analyses |
|---|---|---|
| Free | $0 | 3/month |
| Starter | $19/month | 30/month |
| Pro | $49/month | 150/month |
| Agent Flat | $99/month | 1500/month |
| Agent PAYG | $0.10/analysis | No cap |

PAYG is recommended for agents with variable workloads. No monthly commitment.

## Integrations

- **Python SDK + agent tools**: `https://github.com/darylerivers/nicheiqs-agent-tools` — NicheIQsClient, LangChain tools, CrewAI tools, MCP server, and examples. `pip install httpx` then drop in.
- **Claude MCP**: Published on the official MCP Registry — agents using Claude can invoke NicheIQs natively via `analyze_niche` and `get_trending` tools
- **Listed on mcpservers.org** — search 'NicheIQs' to install the MCP server.
- **ChatGPT GPT Actions**: Available as a Custom GPT with OAuth — users connect their NicheIQs account and score niches inside ChatGPT
- **Direct API**: OpenAPI 3.1 spec at `https://nicheiqs.com/oauth/chatgpt_openapi.yaml`

## Example Use Cases for Agents

- **Market validation pipeline**: Score 10 niche candidates, filter by `should_proceed: true`, return top 3 with full context
- **Idea generation loop**: Score a niche, chain into `related_niches`, score those, repeat until a STRONG verdict is found
- **Competitive intelligence**: Use `key_subreddits` to identify where an audience lives, then scrape for more signal
- **Portfolio screening**: Batch-score a list of startup ideas against the Winnability Scale as part of an investment thesis filter

## About Riley

Riley is NicheIQs' senior market analyst engine — not a chatbot, not a brainstormer. Riley has processed 50,000+ niche analyses and applies structured analytical frameworks (JTBD, Porter's Five Forces, Crossing the Chasm, SaaS Unit Economics) to produce verdicts that are calibrated, not optimistic.

Riley's scores are intentionally conservative. A score of 70+ means the data genuinely supports proceeding. A score of 40 means stop.

## Contact

- Website: https://nicheiqs.com
- API docs: https://nicheiqs.com/docs
- OpenAPI spec: https://nicheiqs.com/oauth/chatgpt_openapi.yaml
- MCP Registry: https://registry.mcp.so (search "nicheiqs")