API guide

The tvlogo.monster API is free, read-only and needs no key. Base URL https://api.tvlogo.monster (also available as https://search.tvlogo.monster/api). Full reference: OpenAPI docs · openapi.json.

Endpoints

Request	Returns
GET /v1/logo?key=CTV.ca@CKYDT	One logo for one key (JSON). `404` if none, `410` if removed.
GET /v1/logo?key=CKY-DT&redirect=true	`302` straight to the PNG (usable directly as `tvg-logo`).
GET /v1/search?q=global	Up to 20 matching channels with their logo URLs.
GET /v1/stations?near=49.9,-97.1&radius_km=50	Canadian TV transmitters by place, distance, province, city, type, licence `class` or affiliate, with logo URLs and cursor paging. `422` explains a bad filter.
GET /v1/stations?class=low_power,translator	Filter by licence class, any of `full_power`, `class_a`, `low_power`, `translator` (comma-separated). Every row carries `class` (and the raw ISED `ised_class`); `type` (main/rebroadcaster) is unchanged.
GET /v1/classes	The class values with station counts and how they are derived: Canada from the ISED CLASS (rebroadcasters = translator, main LP/VLP = low power, other mains = full power, no Class A in Canada); US from the FCC service (map only).
GET /v1/affiliates	Networks and their brands with station counts (values for `affiliate=`).
GET /v1/params	All lookup options, values and defaults.
GET /v1/stats	Catalogue counts and API usage (cached 60 s).

Lookup options

Parameter	Values	Meaning
namespace	auto*, iptv-org, epg.monster, call_sign, provider, name	Which id system the key belongs to. auto tries tvg-id, epg.monster id, call sign, streaming provider channel id, then channel name.
mode	local*, national	local = the station's own logo, falling back to brand -> network -> channel. national = the network logo for every affiliate.
theme	default*, dark, light, mono	Preferred variant. dark = for dark backgrounds, light = for light backgrounds, mono = monochrome. Falls back to default when the variant does not exist (theme_served tells you what you got).
era	current*, historic	current = the logo in use now (new). historic = an older design (old) when we have one, else current.
size	64, 128, 256, 512*	Square PNG size in pixels (transparent canvas). All sizes are pre-rendered on i.tvlogo.monster.

* default

Example (Python)

# pip install requests
import time

import requests

# 1. the key and the options selected above
params = {
    "key": "CTV.ca@CKYDT",  # tvg-id, epg.monster id, call sign or channel name
}

# 2. ask the API; on 429 wait Retry-After seconds and try again (max 3 tries)
for attempt in range(3):
    resp = requests.get("https://api.tvlogo.monster/v1/logo", params=params, timeout=10)
    if resp.status_code != 429:
        break
    time.sleep(max(int(resp.headers.get("Retry-After", "1")), 1))

# 3. 404 = no logo for this key; anything else unexpected raises
if resp.status_code == 404:
    raise SystemExit("no logo for this key")
resp.raise_for_status()
logo = resp.json()

# 4. use the image URL, e.g. as tvg-logo="..." in an M3U playlist
print(logo["image_url"])
# which level answered: station, brand, network or channel
print(logo["resolved_level"])
# True when a fallback was used (e.g. no dark variant -> default)
print(logo["fallback"], logo["theme_served"])

Example response

{
  "key": "CTV.ca@CKYDT", "namespace": "iptv-org", "name": "CTV CKY-DT", "country": "CA",
  "mode": "local", "theme": "default", "era": "current", "size": 512, "found": true,
  "image_url": "https://i.tvlogo.monster/vlhdz.png",
  "resolved_level": "station", "theme_served": "default", "fallback": false,
  "source": "epg-monster", "trademark_note": "Channel logos are trademarks …",
  "data_licence": "CC-BY-4.0 (metadata and mappings only; logo images are not licensed by tvlogo.monster)"
}

Fair use and rate limits

Limits are per IP address (IPv6 per /64): lookups allow a burst of 60 requests and 2 per second sustained. Each response has RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. Over the limit you get 429 with Retry-After; clients that keep ignoring it are blocked temporarily (15 minutes, then 1 hour, 24 hours, 7 days). Please cache results: responses carry ETag and Cache-Control, and image URLs never change for the same version of a logo.

Attribution

Metadata is CC BY 4.0: please credit “tvlogo.monster” with a link. Logo images are trademarks of their owners and are not licensed by us; see Legal.