PIL Developer Documentation
Structured, weekly-updated, source-grounded signals on product demand, buyer language, competitor gaps, pricing benchmarks, and market alerts across 9 pet categories in North America, UK, and Europe.
Quickstart
Every response includes a meta object with signal_meaning_action so your application (or agent) can extract the right level of detail without parsing the full payload.
Authentication
All endpoints require a Bearer token in the Authorization header. During Early Access, API keys are issued manually to approved developers.
Response Schema
Available Categories and Markets
food_nutritionhealth_wellnessplay_enrichmentstyle_identityhygiene_cleaningemotional_memorialoutdoor_adventurecomfort_livingpet_techUK United KingdomFR France / EuropeNA North AmericaEndpoints
Full opportunity assessment combining demand, gaps, pricing, readiness, and trends into a 0-100 directional score.
| Param | Required | Description |
|---|---|---|
category | Yes | One of 9 pet categories |
market | Yes | UK, FR, or NA |
limit | No | Max results (default 10, max 50) |
{
"data": [{
"ppos_score": 66,
"score_tier": "Promising",
"component_scores": {
"demand_strength": 100,
"gap_availability": 93,
"price_viability": 0,
"buyer_readiness": 53,
"trend_momentum": 50
},
"score_rationale": "Strong demand signals in UK. Clear competitive gaps. No pricing data yet.",
"recommended_action": "Promising signals but needs validation on pricing.",
"limitations": "Price viability estimated from limited retail data.",
"data_quality": "ready"
}],
"meta": {
"schema_version": "v1.1",
"freshness": "2026-05-04T00:00:00.000Z",
"valid_until": "2026-05-11T00:00:00.000Z",
"confidence": "medium",
"data_quality": "ready",
"signal_meaning_action": {
"signal": "PPOS 66/100 (Promising). Demand 100, Gap 93, Price 0.",
"meaning": "Strong demand signals in UK...",
"action": "Promising signals but needs validation on pricing."
}
}
}Buyer demand confidence, signal volume, purchaser weighting, emotion drivers, and trend direction.
| Param | Required | Description |
|---|---|---|
category | Yes | Pet category |
market | Yes | UK, FR, or NA |
{
"data": [{
"demand_confidence": 72,
"demand_tier": "Medium-High",
"signal_count": 344,
"purchaser_pct": 35,
"emotion_drivers": [
{ "emotion": "pride", "pct": 45, "example": "..." }
],
"trend": "growing",
"verdict": "Demand signal is strong..."
}],
"meta": { "schema_version": "v1.1", ... }
}Competitive whitespace where demand exists but supply does not address it. Includes demand evidence, supply check, uncontested language.
| Param | Required | Description |
|---|---|---|
category | Yes | Pet category |
market | Yes | UK, FR, or NA |
{
"data": [{
"total_gaps": 3,
"gaps": [{
"title": "Comfort gap",
"demand_evidence": { "signal_count": 12, "purchaser_pct": 58 },
"supply_evidence": { "addressing_gap": 0, "competitors_checked": 20 },
"opportunity": { "confidence": 85, "suggested_positioning": "..." }
}]
}],
"meta": { ... }
}Consumer voice themes (pain points, praise, switching, wishlists), top phrases, and say-this/don't-say-this messaging guidance.
| Param | Required | Description |
|---|---|---|
category | Yes | Pet category |
market | Yes | UK, FR, or NA |
{
"data": [{
"total_signals_analyzed": 280,
"purchaser_pct": 42,
"themes": [{ "theme": "quality_complaints", "type": "pain_point", "frequency": 31 }],
"say_this": ["love it", "best purchase"],
"dont_say_this": ["military-grade", "paradigm"]
}],
"meta": { ... }
}Price range, clusters (entry/mid/premium), top bestsellers, entry and premium thresholds, cross-market comparison.
| Param | Required | Description |
|---|---|---|
category | Yes | Pet category |
market | Yes | UK, FR, or NA |
{
"data": [{
"price_median": 24.99,
"price_currency": "GBP",
"clusters": [{ "label": "Entry", "range": [8, 16], "products": 7 }],
"top_sellers": [{ "name": "...", "brand": "...", "price": 19.99 }]
}],
"meta": { ... }
}Week-over-week changes: new bestsellers, dropped products, price changes, demand spikes, competitor positioning shifts.
| Param | Required | Description |
|---|---|---|
category | Yes | Pet category |
market | Yes | UK, FR, or NA |
{
"data": [{
"total_alerts": 4,
"alerts": [{
"type": "new_bestseller",
"severity": "high",
"title": "New entry: EcoHarness Pro",
"action": "Strong new entrant..."
}]
}],
"meta": { ... }
}Beta API Pricing
During beta, all developer keys start with 100 free credits/month. Different endpoints consume different intelligence credits based on the decision value they provide. Paid tiers from $49/month after beta validation.
| Endpoint | Credits |
|---|---|
opportunity | 10 |
demand | 5 |
gaps | 5 |
voice | 3 |
pricing | 3 |
alerts | 3 |
Beta: Developer Free (100 credits/month). Paid tiers after validation: Builder $49/mo, Operator $199/mo, Platform $799/mo.
For AI Agents
PIL is also available as an MCP server for Claude Desktop and Claude Code. Currently in beta. Same data, same intelligence, structured for tool calling.