Developers

The WhatSphere demographic dataset as a free public beta API.

WhatSphere scores every title on audience demographics, cast composition, adaptation faithfulness, and advocacy signals. The same data behind this site is available as a read-only JSON API. Sign up below for a free beta key — no billing, no card. We just ask what you're building so we can shape the paid tiers later.

Authentication

Send your key on every request as either an X-API-Key header or an Authorization: Bearer token.

curl -H "X-API-Key: wsk_beta_…" \
  "https://whatsphere.com/api/v1/spheres/titles?limit=5"

# or

curl -H "Authorization: Bearer wsk_beta_…" \
  "https://whatsphere.com/api/v1/spheres/search?q=dune"

Check your key's status and usage any time:

curl -H "X-API-Key: wsk_beta_…" "https://whatsphere.com/api/v1/spheres/dev/me"

Rate limits

Beta keys are limited to 60 requests per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; over-limit requests get a 429 with Retry-After. Responses are JSON in a { "data": … } envelope; lists add a pagination cursor.

Endpoints

All endpoints are read-only GET requests under https://whatsphere.com/api/v1/spheres. Submission endpoints (reviews, corrections) and moderation tools are first-party only and not part of the public API.

WhatSphere public API endpoints and their descriptions
Endpoint	Description
GET /titles	Paginated title list
GET /titles/:slug	Full scoring breakdown plus joins (Wikidata, lineage, Steam popularity)
GET /search?q=	Full-text title search
GET /browse	Filter by sphere, race, score ranges, min_confidence, has_source_work, steam_peak_gte
GET /genres / /genres/:slug	Genre index and per-genre listings
GET /compare?ids=	Side-by-side of 2–10 titles
GET /explore	Personalized discovery query
GET /franchise/:slug	Franchise drift analysis
GET /persons/:slug	Actor / creator profile
GET /studios/:slug	Studio filmography + aggregates
GET /orgs/:slug	Advocacy organization profile
GET /insights/:topic	Insight aggregations (race-swaps, lgbtq, etc.)
GET /trends	Demographic trend analytics
GET /stats	Platform-wide statistics
GET /aggregates/:scope	Annual rollups by era/studio/genre/platform
GET /macro/:scope/:key	Evidence-over-time macro reports
GET /stories / /stories/:slug	Published data stories

Trust fields

A title detail's scores object carries the fields the site uses to avoid a dishonest zero. racial_scores_status is computed, insufficient_data, or diluted. When the status is not computed, every racial_audiences value is null — a stored zero is not returned. racial_coverage_pct is the share of the actor cast with a researched race. data_confidence is 0 to 1. Browse accepts min_confidence (the site sends 0.5 unless the visitor turns that filter off). Advocacy is null for documentaries and docuseries because the measure does not apply to non-fiction; that null is not a score of 0 and not the entertainment tier.

{
  "scores": {
    "young_men": 72,
    "young_women": 41,
    "older_men": 55,
    "older_women": 38,
    "faithfulness": null,
    "advocacy": null,
    "advocacy_tier": null,
    "lgbtq_audience": 4,
    "racial_audiences": {
      "white": null,
      "black": null,
      "hispanic": null,
      "asian": null,
      "south_asian": null,
      "middle_eastern": null,
      "indigenous": null,
      "mixed": null,
      "other": null
    },
    "data_confidence": 0.85,
    "racial_scores_status": "insufficient_data",
    "racial_coverage_pct": 12,
    "score_version": 1
  }
}

Compare returns the same rule on the four racial audiences it includes, plus racial_scores_status. GET /browse?min_confidence=0.5 keeps titles at or above that confidence. Omitting min_confidence does not filter.

Sphere joins (beta)

Title detail adds a joins object. It carries external ids, source lineage, a Steam popularity snapshot, and a display copy of faithfulness when the title is an adaptation and a faithfulness score already exists. Joins do not write title_sphere_scores.

joins.external_ids.wikidata_qid and wikidata_status (matched or unmatched). Null status means the title was not looked up.
joins.lineage[] lists source works that are not original, with Open Library id, subjects, and a source_work chip.
joins.faithfulness.score is copied for display beside that lineage. The note says joins do not write the value.
joins.popularity is Steam current_players (value, captured_at, band of low / mid / high). It is null when there is no snapshot. A missing snapshot is not zero.
joins.title_chip is adaptation or null.
joins.attributions names Wikidata (CC0), Open Library, and the Steam Web API when those fields are present.

Revealed preference — not a sphere score.

Steam Web API ISteamUserStats/GetNumberOfCurrentPlayers returns current players, not historical peak. WhatSphere does not scrape SteamCharts. steam_peak_gte filters the latest current_players snapshot from the last 30 days.

GET https://whatsphere.com/api/v1/spheres/titles/john-wick
GET https://whatsphere.com/api/v1/spheres/browse?has_source_work=1
GET https://whatsphere.com/api/v1/spheres/browse?steam_peak_gte=1000&type=video_game

has_source_work=1 or true keeps titles with a source_material row whose type is not original. steam_peak_gte keeps titles whose latestcurrent_players snapshot from the last 30 days is at least that number. Browse rows include popularity or null, same shape as the title panel, so a client can color by band without treating a gap as zero.

Beta terms

Free public beta — no SLA, no uptime or availability guarantee.
Attribute “WhatSphere (whatsphere.com)” wherever you display the data.
The data is for informational use. Don't resell it wholesale or imply endorsement.
Keys may be rate-limited, rotated, or revoked at any time. Paid tiers with higher limits will follow.