subjects-data-api • phases 7 and 8

Persisted subjects data, documented end to end.

This API serves a lightweight index and a full subject payload from persisted score, social and posts tables. It does not recalculate competitive metrics during requests.

Quick start

  1. Send a POST request to index.php with a JSON body.
  2. Include a valid token and one function value: help, index or get.
  3. Use id_list only for get.
  4. Use days_of_history on get when you need a window other than the default 7 days.
Method: POST Format: application/json Auth: token in body Default history: 7 days

Scope and assumptions

  • Competitive fields come from persisted competition snapshots.
  • Filtering by id_list never shrinks the competition universe used for percentile or ranking.
  • competitionKey is based on tournament only, with subject-id fallback when tournament is missing.
  • The current agreed scope excludes YouTube, 90-day publication history and calendar metadata.
  • If token is missing, this HTML guide is returned instead of JSON.
Authentication

Token is required for every JSON request

The API expects a valid token inside the JSON body. The guide is intentionally visible without authentication, but the token value itself is not exposed here. Request it from the maintainer of the deployment.

Missing token returns this HTML guide. Invalid token returns HTTP 401 with a JSON authentication error.
Zone under: r < 0.60 Zone comfort: 0.60 ≤ r < 0.80 Zone elite: r ≥ 0.80
Contract

Request JSON shape

  • token: required string.
  • function: required string with value help, index or get.
  • id_list: required array of positive integer IDs only for get.
  • days_of_history: optional integer for get. Defaults to 7 if omitted or invalid.
{
  "token": "YOUR_TOKEN",
  "function": "get",
  "id_list": [101, 205, 309],
  "days_of_history": 14
}
Functions

Three operations, one endpoint

help

Returns the JSON contract of the API, including request rules, examples and errors.

{
  "token": "YOUR_TOKEN",
  "function": "help"
}

index

Returns a lightweight catalog of competitions and subjects with availability metadata and current score snapshot.

{
  "token": "YOUR_TOKEN",
  "function": "index"
}

get

Returns the full payload for selected subjects, including score history, social series and posts inside the requested time window.

{
  "token": "YOUR_TOKEN",
  "function": "get",
  "id_list": [101, 205],
  "days_of_history": 7
}
Payloads

What each response contains

index response

  • referenceDate and generatedAt for traceability.
  • stale flag at global level.
  • totals with subject and competition counters.
  • competitions with competitionKey, subject counts and stale status.
  • subjects with base metadata, currentScore and availability.

get response

  • subject with base metadata, competitionKey, averageMentionsInRange, score snapshot and current network data.
  • historyCount and postsCount.
  • score.latest plus score.series.score and score.series.percentile.
  • social per platform with followers, interactions, engagementRate and mentions.
  • posts with latestByPlatform, reactionsEvolution, interactionsShareByPlatform and publicationsByPlatform.
Examples

Ready-to-use request and response samples

{
  "token": "YOUR_TOKEN",
  "function": "get",
  "id_list": [124],
  "days_of_history": 7
}
{
  "status": "success",
  "message": "Subjects retrieved successfully.",
  "data": [
	{
	  "subject": {
		"id": 124,
		"name": "Juan Perez",
		"sport": "American Football",
		"tournament": "NFL",
		"team": "Sample Team",
		"position": "Quarterback",
		"competitionKey": "NFL",
		"averageMentionsInRange": 42.5,
		"score": {
		  "date": "2026-05-06",
		  "score": 10345.227541,
		  "zone": "comfort",
		  "tierLabel": "contender",
		  "percentileRank": 0.7425,
		  "totalFollowers": 920000,
		  "audienceBase": 728.44,
		  "multiplier": 1,
		  "activityDecay": 0.71,
		  "posts7d": 5,
		  "platformCount": 3,
		  "rankPosition": 7,
		  "competitorsCount": 20,
		  "delta1d": 112.431,
		  "delta7d": 531.224,
		  "momentumLabel": "rising"
		},
		"networks": {
		  "instagram": {
			"url": "https://instagram.com/example",
			"followers": 450000,
			"following": 1200,
			"publications": 340,
			"averageMentionsInRange": 10.2
		  },
		  "tiktok": {
			"url": "https://tiktok.com/@example",
			"followers": 380000,
			"globalLikes": 1200000,
			"globalViews": 8400000,
			"averageMentionsInRange": 12.4
		  },
		  "facebook": {
			"url": null,
			"followers": 0,
			"following": 0,
			"averageMentionsInRange": 8.1
		  },
		  "x": {
			"url": "https://x.com/example",
			"followers": 90000,
			"following": 300,
			"averageMentionsInRange": 11.8
		  }
		}
	  },
	  "historyCount": 7,
	  "postsCount": 18,
	  "score": {
		"latest": {
		  "date": "2026-05-06",
		  "score": 10345.227541,
		  "zone": "comfort",
		  "tierLabel": "contender",
		  "percentileRank": 0.7425,
		  "totalFollowers": 920000,
		  "audienceBase": 728.44,
		  "multiplier": 1,
		  "activityDecay": 0.71,
		  "posts7d": 5,
		  "platformCount": 3,
		  "rankPosition": 7,
		  "competitorsCount": 20,
		  "delta1d": 112.431,
		  "delta7d": 531.224,
		  "momentumLabel": "rising"
		},
		"series": {
		  "score": [
			{ "x": "2026-05-04", "y": 10040.111111 },
			{ "x": "2026-05-05", "y": 10232.796312 },
			{ "x": "2026-05-06", "y": 10345.227541 }
		  ],
		  "percentile": [
			{ "x": "2026-05-04", "y": 71.1 },
			{ "x": "2026-05-05", "y": 73.35 },
			{ "x": "2026-05-06", "y": 74.25 }
		  ]
		}
	  }
	}
  ]
}
Errors

Failure modes exposed by the endpoint

  • HTTP 400 if function is missing or different from help, index or get.
  • HTTP 400 if get is requested without a non-empty id_list array.
  • HTTP 401 if token is invalid.
  • HTTP 500 if the response cannot be built because of an internal processing error.
Business rules

Competitive behavior and history windows

  • Score, percentile, ranking, zone and tierLabel are always relative to the full competition snapshot persisted for the subject date.
  • Asking for a single subject does not recalculate the competition around that subject.
  • zone is derived only from percentileRank: under for r < 0.60, comfort for 0.60 ≤ r < 0.80 and elite for r ≥ 0.80.
  • tierLabel is derived only from percentileRank: rookie for r < 0.60, contender for 0.60 ≤ r < 0.80, performer for 0.80 ≤ r < 0.90 and elite for r ≥ 0.90.
  • Score thresholds such as 60 or 80 points must not be used to assign percentile-based zones.
  • days_of_history only trims the response window backward from today. It does not change data retention in the database.
  • When days_of_history is omitted or invalid, get falls back to 7 days.
  • GetSubjectsIndex stays intentionally lightweight and always targets the current day view.
  • The API reads from persisted tables and does not trigger online score recomputation.
This guide describes the contract currently implemented by subjects-data-api. For a machine-readable version of the same contract, call the help function with a valid token.