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

Create an account. You receive a live key and a test key immediately.
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.

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, Prime Video, Disney+; current charts) with a small per-IP limit so you can try the API before signing up.

Plan	Countries	Providers	History	Requests / mo
Free	US	netflix, prime, disney	Current only	1,000
Developer	All	All	30 days	50,000
Pro	All	All	Full	500,000
Business	All	All	Full	5,000,000

Playground

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

ProviderCountryTypeAPI key (optional, unlocks your plan)

Without a key, requests use the free scope: United States, Netflix, Prime Video, and Disney+.

GET/v1/charts?provider=paramount&country=IT

curl "https://streamrank.io/v1/charts?provider=paramount&country=IT"

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.

provider	string	Required. netflix, prime, disney, max, hulu, apple, paramount, peacock.
country	string	Required. ISO 3166-1 alpha-2, e.g. US, GB, JP.
type	movie \| tv	Optional. Return one chart instead of both.
date	YYYY-MM-DD	Optional. A past chart. Resolves to the newest chart on or before the date. Requires history on your plan.
limit	1–10	Optional. 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

rank	integer	Position on the chart, 1–10.
previous_rank	integer \| null	Rank the day before, or null if the title was not on yesterday's chart.
rank_change	integer \| null	previous_rank − rank. Positive means it moved up.
is_new	boolean	True on the first day a title appears on this chart.
days_in_top_10	integer	Total days on this chart, including today.
peak_rank	integer	Best rank so far on this chart.
first_charted_at	date	First day on this chart.
title	object	Canonical title: id, slug, name, type, year, tmdb_id, imdb_id, poster_url.

Derived metrics are computed from our own stored history, so they reflect the days we have collected.

Titles

GET/v1/titles/{id}

A canonical title with where it sits on every current chart and lifetime stats. Accepts a title id (ttl_…) or slug.

Example

GET /v1/titles/ttl_5k2m9x1qzc7v
GET /v1/titles/the-whisper-man-2026

GET/v1/titles/{id}/rankings

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

provider	string	Optional filter.
country	string	Optional filter.
from	YYYY-MM-DD	Optional start date.
to	YYYY-MM-DD	Optional end date.
limit	1–5000	Optional. 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": { "allowed_countries": ["US"], "upgrade_url": "/pricing" }
  }
}

400 invalid_request		Missing or malformed parameter. details.issues lists each one.
401 unauthorized		Missing, malformed, or revoked API key.
403 plan_required		The country, provider, or date is outside your plan.
404 not_found		No chart or title for that request.
429 rate_limited		Per-minute limit hit. Check X-RateLimit-Reset.
429 quota_exceeded		Monthly request quota hit.
500 internal_error		Our fault. Retry with backoff.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

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"])

provider	string	Required.
country	string	Required.
limit	1–20	Optional. Items per bucket, default 5.