Statsa Data API Documentation

Comprehensive guide for consuming the Statsa API from external systems and front ends.

1) Quick start

  • Base URL: https://statsa.ai
  • API root: /api/data
  • Auth header: X-Api-Key
  • Content type: JSON responses

Required request headers

X-Api-Key: your-api-key
Accept: application/json

Quick health-style call

curl -H "X-Api-Key: your-api-key" \
  "https://statsa.ai/api/data/weeks/current"

2) Authentication and security

All endpoints are protected and require a valid API key. Requests without a valid key return 401 Unauthorized.

  • Do not expose the key in browser bundles or public repos.
  • Prefer server-side usage for production integrations.
  • Rotate keys periodically and after any suspected exposure.

3) Data conventions

  • Week format: Integer YYYYWW (example: 202624).
  • Sentiment scale: Aggregated score where helper values are mapped to icon/color in some endpoints.
  • IDs: sourceId and articleHash are numeric; personHash is string.
  • Times: Stored and returned as UTC-compatible timestamps.

4) Endpoint index

Utility

  • GET /api/data/weeks/current

People

  • GET /api/data/people
  • GET /api/data/people/{personHash}
  • GET /api/data/people/search
  • GET /api/data/people/top
  • GET /api/data/people/{personHash}/links
  • GET /api/data/people/{personHash}/country-stats

Countries

  • GET /api/data/countries
  • GET /api/data/countries/{countryId}
  • GET /api/data/countries/slug/{slug}
  • GET /api/data/countries/{countryId}/international-attention
  • GET /api/data/countries/{countryId}/domestic-focus

Sources

  • GET /api/data/sources
  • GET /api/data/sources/{sourceId}
  • GET /api/data/sources/{sourceId}/links

Posts

  • GET /api/data/posts/recent
  • GET /api/data/posts/{slug}

Articles

  • GET /api/data/articles/recent
  • GET /api/data/articles/stats
  • GET /api/data/articles/stats/all-time

5) Detailed endpoint reference

GET /api/data/weeks/current

Returns current week and the week value used for typical 4-week windows.

{
  "currentWeek": 202624,
  "last4StartWeek": 202621
}

GET /api/data/people/top

Returns ranked people with computed stats.

Query params: startWeek, endWeek, limit, fresh, countryId, fromCountryId, gender, minAge, maxAge, newsCategory, sortBy=mentions|dominance.

curl -H "X-Api-Key: your-api-key" \
  "https://statsa.ai/api/data/people/top?startWeek=202621&endWeek=202624&limit=20&sortBy=dominance"
[
  {
    "personHash": "elon-musk",
    "fullName": "Elon Musk",
    "mentionCount": 412,
    "gender": 1,
    "fromCountryId": 840,
    "fromCountryName": "United States",
    "birthDate": "1971-06-28T00:00:00",
    "persistence": 3,
    "dominance": 8.53,
    "reach": 1250483942.12,
    "power": 4783849302841.55,
    "sentiment": 5.42,
    "sentimentColor": "#809D3C",
    "sentimentFace": "fa-face-smile",
    "snippets": [],
    "reason": "",
    "countryRows": [],
    "rank": 1
  }
]

GET /api/data/people/{personHash}/links?limit=100&includeContext=true

Returns person-article links. With includeContext=true, each item includes article/source/country metadata, sentiment display fields, and people mentioned in that article.

[
  {
    "personHash": "elon-musk",
    "articleHash": 638838091234567890,
    "mentionDate": "2026-05-24T00:00:00",
    "snippet": "Musk announced...",
    "sentiment": 6,
    "sentimentColor": "#32CD32",
    "sentimentFace": "fa-face-grin",
    "articleTitle": "Major industry update",
    "articleUrl": "https://example.com/news/major-update",
    "articlePeople": "elon-musk,donald-trump,sam-altman",
    "otherPeople": ["donald-trump", "sam-altman"],
    "sourceId": 12,
    "sourceName": "Example News",
    "sourceUrl": "https://example.com",
    "countryId": 840,
    "countryName": "United States",
    "countryIso": "US"
  }
]

GET /api/data/people/{personHash}/country-stats

Returns country-level distribution and global aggregates for a person in a week range.

{
  "startWeek": 202621,
  "endWeek": 202624,
  "globalDominance": 0.074,
  "globalSentiment": 5.26,
  "globalReach": 833284920.22,
  "globalPower": 3029482038472.9,
  "persistence": 3,
  "countries": [
    {
      "countryId": 840,
      "countryName": "United States",
      "countryIso": "US",
      "mentions": 142,
      "articles": 1203,
      "population": 331002651,
      "gdp": 22996100000000,
      "persistence": 3,
      "localDominance": 0.118,
      "reach": 47051944.0,
      "power": 3274078300000.0,
      "sentiment": 5.43
    }
  ]
}

GET /api/data/posts/recent?count=3

Returns most recent published posts.

[
  {
    "postId": 518,
    "title": "Weekly Top 10",
    "slug": "weekly-top-10-202624",
    "content": "{...}",
    "summary": "This week saw...",
    "imagePath": "elon-musk",
    "status": "published",
    "view": "WeeklyRecap",
    "createdAt": "2026-05-25T10:21:11",
    "updatedAt": "2026-05-25T10:21:11"
  }
]

GET /api/data/articles/stats?days=1

{
  "days": 1,
  "totalArticles": 18342,
  "totalSources": 428,
  "totalCountries": 91
}

GET /api/data/articles/recent?limit=100&includeSourceContext=true

[
  {
    "articleHash": 638838091234567890,
    "url": "https://example.com/news/story",
    "title": "Headline",
    "sourceId": 12,
    "people": "elon-musk,donald-trump",
    "sourceName": "Example News",
    "sourceStatus": "active",
    "countryId": 840,
    "countryName": "United States",
    "countryIso": "US"
  }
]

GET /api/data/sources?countryId=840

[
  {
    "sourceId": 12,
    "name": "Example News",
    "url": "https://example.com",
    "countryId": 840,
    "description": "General news",
    "lastCheckedDate": "2026-05-26T00:00:00",
    "status": "active",
    "linkFilter": "/news/",
    "createdAt": "2025-12-01T00:00:00",
    "updatedAt": "2026-05-26T00:00:00",
    "country": null
  }
]

GET /api/data/sources/{sourceId}/links?applyFilter=true

{
  "source": {
    "sourceId": 12,
    "name": "Example News"
  },
  "allLinks": [
    "https://example.com/news/story-a",
    "https://example.com/news/story-b"
  ],
  "matchedLinks": [
    "https://example.com/news/story-a"
  ],
  "unmatchedLinks": [
    "https://example.com/news/story-b"
  ]
}

GET /api/data/countries/{countryId}/international-attention

{
  "countryId": 840,
  "percentage": 4.91,
  "rank": 2,
  "outOf": 91,
  "median": 0.88
}

GET /api/data/countries/{countryId}/domestic-focus

{
  "countryId": 840,
  "startWeek": 202620,
  "endWeek": 202624,
  "focusPercent": 38.44,
  "rank": 18,
  "outOf": 91,
  "median": 42.01
}

6) Home page equivalent call pattern (generic API only)

  1. GET /api/data/weeks/current
  2. GET /api/data/people/top?startWeek={endWeek}&endWeek={endWeek}&limit=12&fresh=true
  3. GET /api/data/people/top?startWeek={last4StartWeek}&endWeek={endWeek}&limit=100&sortBy=dominance
  4. GET /api/data/posts/recent?count=3
  5. GET /api/data/articles/stats?days=1

7) Error model and status codes

  • 200 OK: successful query.
  • 400 Bad Request: invalid range or query combination (for example missing all inputs on /people/search).
  • 401 Unauthorized: missing or invalid API key.
  • 404 Not Found: missing resource (person/source/post/country).
  • 500 Internal Server Error: server-side failure.

Typical error body

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-..."
}

8) Integration guidance

  • Prefer selective calls (limit, filters) over full-dataset pulls in frequent polling jobs.
  • Cache stable datasets like countries and sources where possible.
  • Treat unknown/null fields as expected for partial or optional data.
  • When building analytics, pin explicit startWeek/endWeek for reproducible results.
  • Versioning: current endpoints are unversioned under /api/data; treat additive fields as non-breaking and plan schema-tolerant clients.

9) End-to-end cURL examples

curl -H "X-Api-Key: your-api-key" \
  "https://statsa.ai/api/data/people/top?limit=20&sortBy=mentions"

curl -H "X-Api-Key: your-api-key" \
  "https://statsa.ai/api/data/people/search?q=elon&limit=10"

curl -H "X-Api-Key: your-api-key" \
  "https://statsa.ai/api/data/people/elon-musk/links?limit=50&includeContext=true"

curl -H "X-Api-Key: your-api-key" \
  "https://statsa.ai/api/data/articles/recent?limit=50&includeSourceContext=true"

curl -H "X-Api-Key: your-api-key" \
  "https://statsa.ai/api/data/countries/840/domestic-focus?startWeek=202620&endWeek=202624"