API: Discover

Discover

Rankings, trending, and editorially featured content.

GET Rankings

GET /v1/rankings

Returns the overall popularity ranking of media in a country, combining availability across providers, ratings, and recency.

Requires Authorization: Bearer header

Parameters

country query required

ISO 3166-1 alpha-2 country code

string

limit query

integer default: 50

offset query

integer default: 0

kind query

Filter by content type

string movietv_show

Responses

200 Rankings

400 Missing required parameter

Response schema 200

resultsobject[]required

idstringrequired

slugstringrequired

titlestringrequired

original_titlestringrequirednullable

yearintegerrequirednullable

kindmovie | tv_showrequired

posterstringrequirednullable

backdropstringrequirednullable

genresstring[]required

popularitynumberrequired

tmdb_ratingnumberrequirednullable

positionintegerrequired

scorenumberrequired

pointsnumberrequired

totalintegerrequired

Total number of items (before pagination)

limitintegerrequired

offsetintegerrequired

countrystringrequired

Try it

Bearer token

Get an API key

country *

limit

offset

kind -- none -- movie tv_show

curl JavaScript Python Copy

curl -X GET 'https://popcorntime-api-production.wicked-f82.workers.dev/v1/rankings?country=US&limit=50' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const res = await fetch('https://popcorntime-api-production.wicked-f82.workers.dev/v1/rankings?country=US&limit=50', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await res.json();

import requests

res = requests.get('https://popcorntime-api-production.wicked-f82.workers.dev/v1/rankings?country=US&limit=50',
    headers={'Authorization': 'Bearer YOUR_API_KEY'})
data = res.json()

Send request

// Example response
null

GET Trending

GET /v1/trending

Daily trending titles based on position changes in the catalog. Shows what's gaining popularity right now.

Requires Authorization: Bearer header

Parameters

country query required

ISO 3166-1 alpha-2 country code

string

limit query

integer default: 20

kind query

Filter by content type

string movietv_show

Responses

200 Trending results

400 Missing required parameter

Response schema 200

resultsobject[]required

idstringrequired

slugstringrequired

titlestringrequired

original_titlestringrequirednullable

yearintegerrequirednullable

kindmovie | tv_showrequired

posterstringrequirednullable

backdropstringrequirednullable

genresstring[]required

popularitynumberrequired

tmdb_ratingnumberrequirednullable

positionintegerrequired

scorenumberrequired

pointsnumberrequired

totalintegerrequired

Total number of items (before pagination)

limitintegerrequired

offsetintegerrequired

countrystringrequired

Try it

Bearer token

Get an API key

country *

limit

kind -- none -- movie tv_show

curl JavaScript Python Copy

curl -X GET 'https://popcorntime-api-production.wicked-f82.workers.dev/v1/trending?country=US&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const res = await fetch('https://popcorntime-api-production.wicked-f82.workers.dev/v1/trending?country=US&limit=20', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await res.json();

import requests

res = requests.get('https://popcorntime-api-production.wicked-f82.workers.dev/v1/trending?country=US&limit=20',
    headers={'Authorization': 'Bearer YOUR_API_KEY'})
data = res.json()

Send request

// Example response
null

GET Featured

GET /v1/featured

Hand-picked featured media, refreshed daily and weekly.

Requires Authorization: Bearer header

Parameters

country query required

ISO 3166-1 alpha-2 country code

string

kind query

Feature period

string dayweek default: week

Responses

200 Featured media

400 Missing required parameter

Response schema 200

countrystringrequired

kindday | weekrequired

mediaobject[]required

idstringrequired

slugstringrequired

titlestringrequired

original_titlestringrequirednullable

yearintegerrequirednullable

kindmovie | tv_showrequired

posterstringrequirednullable

backdropstringrequirednullable

genresstring[]required

popularitynumberrequired

tmdb_ratingnumberrequirednullable

taglinestringrequirednullable

overviewstringrequirednullable

rankintegerrequired

featured_fromstringrequirednullable

collectionsobject[]required

idintegerrequired

slugstringrequired

namestringrequired

descriptionstringrequirednullable

rankintegerrequired

featured_fromstringrequirednullable

Try it

Bearer token

Get an API key

country *

kind -- none -- day week

curl JavaScript Python Copy

curl -X GET 'https://popcorntime-api-production.wicked-f82.workers.dev/v1/featured?country=US' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const res = await fetch('https://popcorntime-api-production.wicked-f82.workers.dev/v1/featured?country=US', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await res.json();

import requests

res = requests.get('https://popcorntime-api-production.wicked-f82.workers.dev/v1/featured?country=US',
    headers={'Authorization': 'Bearer YOUR_API_KEY'})
data = res.json()

Send request

// Example response
{
  "country": "string",
  "kind": "day",
  "media": [],
  "collections": [
    {
      "id": 0,
      "slug": "string",
      "name": "string",
      "description": "string",
      "rank": 0,
      "featured_from": "string"
    }
  ]
}