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, name | Which id system the key belongs to. auto tries tvg-id, epg.monster id, call sign, 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.