StreamRank

API documentation

One REST API for daily Top 10 rankings across every major streaming provider and country. Plain JSON, human-readable identifiers, cache-friendly responses.

Base URL

https://streamrank.io/v1

Format

JSON over HTTPS

Auth

Bearer API key

Quickstart

  1. Create an account. You receive a live key and a test key immediately.
  2. Make your first request:
curl
curl "https://streamrank.io/v1/charts?provider=netflix&country=US&type=movie" \
  -H "Authorization: Bearer sk_live_…"

You get the current Netflix Top 10 movies in the United States:

200 OK
{
  "data": {
    "provider": "netflix",
    "country": "US",
    "type": "movie",
    "date": "2026-09-10",
    "updated_at": "2026-09-10T22:49:43.000Z",
    "rankings": [
      {
        "rank": 1,
        "previous_rank": 3,
        "rank_change": 2,
        "is_new": false,
        "days_in_top_10": 8,
        "peak_rank": 1,
        "first_charted_at": "2026-09-03",
        "title": {
          "id": "ttl_5k2m9x1qzc7v",
          "slug": "the-whisper-man-2026",
          "name": "The Whisper Man",
          "type": "movie",
          "year": 2026,
          "tmdb_id": 860508,
          "imdb_id": "tt11561116",
          "poster_url": "https://image.tmdb.org/t/p/w500/….jpg"
        }
      }
    ]
  }
}

Charts update once a day. Cache responses as long as you like. We meter dataset access (countries, providers, history), not how often you fetch.

Authentication

Send your key in the Authorization header. Live keys start with sk_live_ and count toward your plan. Test keys start with sk_test_, return real data in the free scope, and never count toward quota.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Requests without a key work in the free scope (United States; Netflix; current charts) at 10 requests per minute and 200 per calendar month per IP, so you can try the API before signing up.

PlanCountriesProvidersHistoryTrending listRequests / mo
FreeUSnetflixCurrent onlyTop 101,000
DeveloperAllAll30 daysTop 10050,000
ProAllAllFullTop 100500,000
BusinessAllAllFullTop 1005,000,000

Playground

Real requests against the live API. Runs in the free scope until you add a key.

Without a key, requests use the free scope: United States; Netflix; current charts.

GET/v1/charts?provider=prime&country=CA
curl "https://streamrank.io/v1/charts?provider=prime&country=CA"
Response
Run a request to see the response.

Charts

GET/v1/charts

The Top 10 for one provider in one country. Omit type to receive both the movie and TV charts in one response.

providerstringRequired. netflix, prime, disney, max, hulu, apple, paramount, peacock.
countrystringRequired. ISO 3166-1 alpha-2, e.g. US, GB, JP.
typemovie | tvOptional. Return one chart instead of both.
dateYYYY-MM-DDOptional. A past chart. Resolves to the newest chart on or before the date. Requires history on your plan.
limit1–10Optional. Return only the top N.
Examples
GET /v1/charts?provider=netflix&country=US&type=movie
GET /v1/charts?provider=netflix&country=JP&type=tv
GET /v1/charts?provider=disney&country=GB
GET /v1/charts?provider=max&country=US&type=tv&date=2026-09-01

Ranking fields

rankintegerPosition on the chart, 1–10.
previous_rankinteger | nullRank the day before, or null if the title was not on yesterday's chart.
rank_changeinteger | nullprevious_rank − rank. Positive means it moved up.
is_newbooleanTrue on the first day a title appears on this chart.
days_in_top_10integerTotal days on this chart, including today.
peak_rankintegerBest rank so far on this chart.
first_charted_atdateFirst day on this chart.
titleobjectCanonical title: id, slug, name, type, year, tmdb_id, imdb_id, poster_url.

We compute the derived metrics from our own stored history, so they cover the days we have collected.

Titles

GET/v1/titles

Look up a title by name, IMDb id, or TMDB id. Returns a ranked list; ambiguous names are not a 404. Then call /v1/titles/{id} for current positions.

qstringName, slug, ttl_ id, IMDb id, or TMDB id. Required unless imdb_id or tmdb_id is set.
imdb_idstringExact IMDb id, e.g. tt4574334.
tmdb_idintegerExact TMDB id. Pass type when a movie and a show share the number.
typemovie | tvOptional. Restrict results to one kind.
yearintegerOptional. Prefer titles released this year when matching by name.
limit1–20Optional. Default 10.
Examples
GET /v1/titles?q=The+Pitt
GET /v1/titles?imdb_id=tt4574334
GET /v1/titles?tmdb_id=1396&type=tv
GET /v1/titles?q=Ready+or+Not&year=2019
200 OK
{
  "data": [
    {
      "id": "ttl_5k2m9x1qzc7v",
      "slug": "the-whisper-man-2026",
      "name": "The Whisper Man",
      "type": "movie",
      "year": 2026,
      "tmdb_id": 860508,
      "imdb_id": "tt11561116",
      "poster_url": "https://image.tmdb.org/t/p/w500/….jpg",
      "match": "name"
    }
  ],
  "meta": {
    "count": 1
  }
}
GET/v1/titles/{id}

A canonical title with where it currently ranks, plus stats over the history your plan includes. Countries and providers follow the same entitlements as /v1/charts. Accepts a title id (ttl_…), slug, IMDb id, or TMDB id.

Example
GET /v1/titles/ttl_5k2m9x1qzc7v
GET /v1/titles/the-whisper-man-2026
GET /v1/titles/tt11561116
GET/v1/titles/{id}/rankings

Day-by-day ranking history for a title, newest first, clamped to your plan's history window.

providerstringOptional filter.
countrystringOptional filter.
fromYYYY-MM-DDOptional start date.
toYYYY-MM-DDOptional end date.
limit1–5000Optional. Default 1000.
200 OK
{
  "data": [
    {
      "date": "2026-09-10",
      "provider": "netflix",
      "country": "US",
      "type": "movie",
      "rank": 3,
      "previous_rank": 1,
      "rank_change": -2,
      "days_in_top_10": 13,
      "peak_rank": 1
    }
  ],
  "meta": {
    "title_id": "ttl_5k2m9x1qzc7v",
    "from": "2026-08-11",
    "to": "2026-09-10",
    "history_days": 30
  }
}

Countries

GET/v1/countries

Every country with chart data and the providers available in each, plus whether your plan includes it.

200 OK
{
  "data": [
    {
      "code": "US",
      "name": "United States",
      "providers": [
        "netflix",
        "prime",
        "disney",
        "max",
        "hulu",
        "apple",
        "paramount",
        "peacock"
      ],
      "included_in_plan": true
    }
  ]
}

Providers

GET/v1/providers
200 OK
{
  "data": [
    {
      "id": "netflix",
      "name": "Netflix",
      "countries": [
        "AU",
        "CA",
        "DE",
        "FR",
        "GB",
        "JP",
        "US"
      ],
      "included_in_plan": true
    },
    {
      "id": "prime",
      "name": "Prime Video",
      "countries": [
        "…"
      ],
      "included_in_plan": true
    }
  ]
}

Errors

Errors are JSON with a stable code and a human-readable message.

403 Forbidden
{
  "error": {
    "code": "plan_required",
    "message": "Country \"JP\" is not included in the Free plan.",
    "details": {
      "param": "country",
      "requested": "JP",
      "allowed_countries": [
        "US"
      ],
      "hint": "Use country=US, or send a key for a plan that includes JP.",
      "upgrade_url": "https://streamrank.io/pricing",
      "docs_url": "https://streamrank.io/docs.md#authentication"
    }
  }
}
400 invalid_requestMissing or malformed parameter. details.hint says how to fix it.
401 unauthorizedMalformed or revoked API key. Omit the header for the free anonymous scope.
403 plan_requiredThe country, provider, or date is outside your plan. details lists allowed values and upgrade_url.
404 not_foundNo chart or title for that request. For titles, search GET /v1/titles?q=.
429 rate_limitedPer-minute limit hit. Honor Retry-After. Check X-RateLimit-Reset.
429 quota_exceededMonthly request quota hit. Honor Retry-After or upgrade.
500 internal_errorOur fault. Retry with backoff.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. 429 responses also send Retry-After. Errors include details.docs_url and, when useful, details.hint with the next legal call.

SDKs

The API is plain HTTP, so any client works. Official SDKs are coming; until then:

JavaScript
const res = await fetch(
  "https://streamrank.io/v1/charts?provider=netflix&country=US&type=movie",
  { headers: { Authorization: `Bearer ${process.env.STREAMRANK_KEY}` } }
);
const { data } = await res.json();
console.log(data.rankings[0].title.name);
Python
import os, requests

r = requests.get(
    "https://streamrank.io/v1/charts",
    params={"provider": "netflix", "country": "US", "type": "movie"},
    headers={"Authorization": f"Bearer {os.environ['STREAMRANK_KEY']}"},
)
for item in r.json()["data"]["rankings"]:
    print(item["rank"], item["title"]["name"])