API Documentation

Access Rating BD data programmatically through our REST API. All endpoints require an API key.

v1Base URL:https://rating.bd/api

Overview

The Rating BD API provides access to channel rankings, person appearance data, content metrics, and leaderboard data. All responses are in JSON format.

Quick Start

# Get top channels
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://rating.bd/api/v1/leaderboards/channels?period=daily"

# Get person details with filmography & social links
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://rating.bd/api/v1/persons/{id}"

# Export persons (for integrations)
curl -H "X-API-Key: rk_your_api_key" \
  "https://rating.bd/api/v1/export/persons?pageSize=100"

# Search content
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://rating.bd/api/v1/content?search=natok"

Authentication

All API requests require an API key passed via the X-Api-Key header. Requests without a valid key will receive a 401 Unauthorized response.

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://rating.bd/api/v1/channels

To request an API key, please contact us. Include your use case and expected request volume.

Channels

GET/v1/channels

List all tracked channels with pagination

Parameters

pagenumberPage number (default: 1)

pageSizenumberItems per page (default: 20, max: 100)

searchstringSearch by name or handle

GET/v1/channels/{id}

Get detailed information about a specific channel

Parameters

iduuidrequiredChannel ID

Persons

GET/v1/persons/{id}

Get detailed information about a person including aliases, types, filmography, and external links

Parameters

iduuidrequiredPerson ID

Content

GET/v1/content

List content items with filtering

Parameters

pagenumberPage number (default: 1)

pageSizenumberItems per page (default: 20)

channelIduuidFilter by channel

categorystringFilter by category slug

searchstringSearch by title

GET/v1/content/{id}

Get detailed content information with metrics

Parameters

iduuidrequiredContent ID

Leaderboards

GET/v1/leaderboards/{type}

Get ranked leaderboard data

Parameters

typestringrequiredchannels, artists, or content

periodstringdaily or weekly (default: daily)

categorystringFilter by category slug (content only)

datestringSpecific date (YYYY-MM-DD)

Export API

The Export API provides bulk access to person and appearance data for external integrations. All export endpoints require a valid API key via the X-API-Key header. API keys can be managed through the admin dashboard.

GET/v1/export/persons

Paginated list of persons with aliases, types, appearance counts, and external links

Parameters

pagenumberPage number (default: 1)

pageSizenumberItems per page (default: 50, max: 200)

sincedatetimeOnly return persons updated after this timestamp

searchstringSearch by name or alias

GET/v1/export/persons/{id}/appearances

All appearances for a person with content details, verification status, and timestamps

Parameters

iduuidrequiredPerson ID

GET/v1/export/content/{id}/appearances

All detected persons for a content item with confidence scores and verification status

Parameters

iduuidrequiredContent item ID

Rate Limits

Each API key has rate limits to ensure fair usage and availability:

Endpoint	Limit	Window
All endpoints	100 requests	per minute
Search endpoints	30 requests	per minute

Rate limit headers are included in all responses:X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset