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

2) Authentication and security

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

3) Data conventions

  • Week format: integer YYYYWW (example: 202624).
  • IDs: sourceId and articleHash are numeric; personHash is string.
  • Timestamps: UTC-compatible date values.
  • Optional fields: nullable fields can be null.

4) Endpoint index

Utility

People

Sources

Countries

Posts

Articles

5) Detailed endpoint reference

GET /api/data/weeks/current

Purpose: get the current week and default 4-week start point.

Response:

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

GET /api/data/people

Purpose: returns all people across all shards.

Response: array of person objects.

[
  {
    "personHash": "elon-musk",
    "fullName": "Elon Musk",
    "description": "Business leader",
    "gender": 1,
    "category": "Business",
    "countryId": 840,
    "countryName": null,
    "birthDate": "1971-06-28T00:00:00",
    "createdAt": "2025-01-01T00:00:00",
    "updatedAt": "2026-05-27T00:00:00"
  }
]

GET /api/data/people/{personHash}

Purpose: fetch a single person by hash.

Path params: personHash (required).

200 response:

{
  "personHash": "elon-musk",
  "fullName": "Elon Musk",
  "description": "Business leader",
  "gender": 1,
  "category": "Business",
  "countryId": 840,
  "countryName": null,
  "birthDate": "1971-06-28T00:00:00",
  "createdAt": "2025-01-01T00:00:00",
  "updatedAt": "2026-05-27T00:00:00"
}

404: person not found.

Purpose: fast person search across shards.

Requires: at least one of q, personHash, or fullName.

Query params: q, personHash, fullName, exactName, countryId, gender, limit (1-100).

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

Response: same person shape as above, returned in an array.

GET /api/data/people/top

Purpose: ranked people over a week range with computed stats.

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

Response: array of person stats objects including mentionCount, dominance, reach, power, sentiment, rank.

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
  }
]

Purpose: article links for one person.

Query params: limit (1-250), includeContext (default true).

Response with context:

[
  {
    "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

Purpose: per-country metrics and global metrics for one person over a week range.

Query params: startWeek, endWeek (optional).

Response:

{
  "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/sources

Purpose: list sources, optionally filtered by country.

Query params: countryId (optional).

curl -H "X-Api-Key: your-api-key" \
  "https://statsa.ai/api/data/sources?countryId=840"

Response: array of source objects.

[
  {
    "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}

Purpose: fetch one source by ID.

Response: single source object.

{
  "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
}

Purpose: extract homepage links and optionally apply source regex filter.

Query params: applyFilter (default 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

Purpose: list all countries.

Response: array of country objects.

[
  {
    "countryId": 840,
    "countryName": "United States",
    "countryIso": "US"
  }
]

GET /api/data/countries/{countryId}

Purpose: fetch country by numeric ID.

Response: single country object.

{
  "countryId": 840,
  "countryName": "United States",
  "countryIso": "US"
}

GET /api/data/countries/slug/{slug}

Purpose: fetch country by slug.

Response: single country object.

{
  "countryId": 840,
  "countryName": "United States",
  "countryIso": "US"
}

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

Purpose: country international attention share and ranking.

Response:

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

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

Purpose: domestic focus metrics and ranking for a week range.

Query params: startWeek, endWeek (optional).

Response:

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

GET /api/data/posts/recent

Purpose: recent published posts.

Query params: count (1-50).

Response: array of post objects.

[
  {
    "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/posts/{slug}

Purpose: fetch a single post by slug.

Response: single post object.

{
  "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/recent

Purpose: recent articles, optional source/country context join.

Query params: limit (1-500), includeSourceContext (default true).

Response: array of article objects.

[
  {
    "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/articles/stats

Purpose: aggregate counts over a rolling day window.

Query params: days (1-365).

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

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

Purpose: aggregate all-time counts.

{
  "totalArticles": 5128301,
  "totalSources": 428,
  "totalCountries": 91
}

6) Error model and status codes

  • 200 OK: successful query.
  • 400 Bad Request: invalid query combination.
  • 401 Unauthorized: missing or invalid API key.
  • 404 Not Found: resource not found.
  • 500 Internal Server Error: server-side failure.

7) Integration guidance

  • Use filtered queries and limits for better performance.
  • Cache stable datasets like countries and sources.
  • Design clients to tolerate additive fields over time.