Build on FanFad

API Documentation

Access fandom momentum data programmatically with the FanFad REST API. Query trending rankings, entity scores, historical momentum, and geographic breakouts — all in real time.

Explore Endpoints Getting Started

Getting Started

Everything you need to make your first API call in under five minutes.

Authentication

Authenticate every request by including your API key in the X-FanFad-Key header. Generate keys from your account dashboard under the API Keys section.

// Request header
X-FanFad-Key: your_api_key_here

Base URL

All API requests are made to the FanFad API base URL. Use HTTPS for all production traffic. Responses are returned in JSON format with UTF-8 encoding.

// Base URL
https://api.fanfad.com/v1

Rate Limits

Rate limits are enforced per API key and vary by plan tier. Rate limit status is returned in response headers so you can monitor usage in real time.

Free / Sandbox100 req/min
Premium1,000 req/min
EnterpriseUnlimited

Core Endpoints

Six RESTful endpoints give you complete access to FanFad's momentum intelligence layer.

GET /trending

Live Trending Rankings

Returns the top entities ranked by FanFad Score. Filter by category, time window, and momentum tier. Supports pagination for large result sets.

{ "data": [ { "id": "ent_8xK2m", "name": "Lumi Voss", "score": 94, "tier": "fire", "category": "internet-creators" } ] }
GET /entities/{id}

Entity Details

Returns detailed momentum data for a single entity, including composite score, lifecycle stage, velocity metrics, and per-platform engagement breakdowns.

{ "data": { "id": "ent_8xK2m", "score": 94, "lifecycle": "viral_ignition", "velocity": 12.4, "platforms": { "tiktok": 96, "youtube": 88 } } }
GET /entities/{id}/history

Historical Momentum Data

Returns historical score and velocity data for a given entity. Supports 30-day, 90-day, and 365-day windows with configurable granularity (hourly, daily, weekly).

{ "data": { "entity_id": "ent_8xK2m", "window": "30d", "points": [ { "date": "2026-02-01", "score": 72 }, { "date": "2026-02-15", "score": 88 } ] } }
GET /categories

List All Categories

Returns all available fandom categories with aggregate statistics including entity count, average score, and top-performing entity per category.

{ "data": [ { "slug": "internet-creators", "name": "Internet Creators", "entity_count": 512, "avg_score": 61.3 } ] }
GET /compare

Compare Entities

Compare two entities side-by-side across all momentum dimensions. Returns parallel score breakdowns, velocity differentials, and lifecycle stage comparison.

{ "data": { "entity_a": { "id": "ent_8xK2m", "score": 94 }, "entity_b": { "id": "ent_3pR7n", "score": 78 }, "delta": 16 } }
GET /heatmap

Geographic Breakout Data

Returns geographic momentum data broken out by region, country, and city. Identify where fandom energy is concentrated and which regions are driving breakout growth.

{ "data": { "entity_id": "ent_8xK2m", "regions": [ { "country": "US", "city": "Los Angeles", "intensity": 92 }, { "country": "KR", "city": "Seoul", "intensity": 88 } ] } }

Response Format

All API responses follow a consistent JSON structure with status, data, and metadata fields.

Standard Response Envelope

{ "status": "success", "data": { "id": "ent_8xK2m", "name": "Lumi Voss", "score": 94, "tier": "fire", "lifecycle": "viral_ignition", "velocity": 12.4, "category": "internet-creators", "platforms": { "tiktok": 96, "youtube": 88, "instagram": 79, "x": 72, "reddit": 65 }, "updated_at": "2026-03-03T12:00:00Z" }, "meta": { "request_id": "req_a1b2c3d4", "rate_limit_remaining": 994, "rate_limit_reset": 1709467260 } }

SDKs & Libraries

Official client libraries to help you integrate FanFad data into your application in minutes.

JavaScript / Node.js

Official JavaScript SDK with full TypeScript support. Works in Node.js and modern browsers.

// Install via npm
npm install @fanfad/sdk

Python

Python client library compatible with Python 3.8 and above. Async support included out of the box.

# Install via pip
pip install fanfad

Ruby

Ruby gem for Rails and standalone Ruby applications. Supports Ruby 3.0 and above with built-in retry logic.

# Install via gem
gem install fanfad

Frequently Asked Questions

Common questions about the FanFad API, authentication, and usage.

API keys are available on the Premium and Enterprise plans. After signing up, navigate to your account dashboard and generate a key from the API Keys section. Free-tier users can request a sandbox key with limited rate limits for testing purposes.
Rate limits depend on your plan tier. Free sandbox keys are limited to 100 requests per minute. Premium plans allow 1,000 requests per minute. Enterprise plans have unlimited rate limits with dedicated infrastructure. Rate limit headers are included in every API response.
Free-tier users can request a sandbox API key for development and testing. Sandbox keys have reduced rate limits (100 requests per minute) and access to a subset of endpoints. Full API access with all endpoints and higher rate limits is available on Premium and Enterprise plans.
All API responses are returned in JSON format. Every response includes a status field, a data object or array containing the requested information, and a meta object with pagination details and rate limit information. Error responses follow the same structure with an additional error object containing a code and human-readable message.

Ready to Build?

Get your API key today and start integrating fandom momentum data into your applications. Free sandbox access is available to get started immediately.

Get API Access Contact Sales