tvlogo.monster API v0.2.0

Generated from the live OpenAPI 3.1.0 document, so it always matches the running API. Raw: Swagger UI · AI prompt (paste into any AI assistant to have it write a tool against this API).

Free, non-profit, read-only API for TV channel logos (Canada first). One key in, one logo out: an iptv-org tvg-id, an epg.monster channel id, a Canadian call sign or a channel name.

Rate limits: per IP token bucket (burst 60, 2/s sustained for lookups). Every response carries RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset; over the limit you get 429 with Retry-After. Repeated violations lead to temporary blocks (15 min, 1 h, 24 h, 7 d).

Legal: logos are trademarks and/or copyright of their owners and are provided for identification only, as-is, without warranty; tvlogo.monster is not affiliated with any broadcaster. Metadata is CC BY 4.0. See https://search.tvlogo.monster/legal

Base URL https://api.tvlogo.monster · no API key · JSON over HTTPS.

GET /v1/logo

Resolve one key to one logo

Parameter	Type	Values · default	Description
key required query	string max len 200		tvg-id (CTV.ca@CKYDT), epg.monster id (CTV.Winnipeg.ca), call sign (CKY-DT) or channel name (CTV Winnipeg)
namespace query	string	`auto` `iptv-org` `epg.monster` `call_sign` `name` default "auto"	Which id system the key belongs to. auto tries tvg-id, epg.monster id, call sign, then channel name.
mode query	string	`local` `national` default "local"	local = the station's own logo, falling back to brand -> network -> channel. national = the network logo for every affiliate.
theme query	string	`default` `dark` `light` `mono` default "default"	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 query	string	`current` `historic` default "current"	current = the logo in use now (new). historic = an older design (old) when we have one, else current.
size query	string	`64` `128` `256` `512` default "512"	Square PNG size in pixels (transparent canvas). All sizes are pre-rendered on i.tvlogo.monster.
redirect query	boolean	default false	302 straight to the PNG instead of JSON (handy as tvg-logo in M3U playlists)

Responses

200 Logo found (or key known but no logo: found=false, 404)

{
  "key": "CTV.ca@CKYDT",
  "namespace": "iptv-org",
  "matched_key": "ctv.ca@ckydt",
  "name": "CTV CKY-DT",
  "country": "CA",
  "mode": "local",
  "theme": "default",
  "era": "current",
  "size": 128,
  "found": true,
  "image_url": "https://i.tvlogo.monster/vlhdz-128.png",
  "public_id": "vlhdz",
  "resolved_level": "station",
  "theme_served": "default",
  "era_served": "current",
  "fallback": false,
  "source": "epg-monster",
  "source_url": "http://dtil.tmsimg.com/assets/s72769_ll_h15_aa.png?w=360&h=270",
  "licence": null,
  "trademark_note": "Channel logos are trademarks and/or copyright of their respective owners. ...",
  "data_licence": "CC-BY-4.0 (metadata and mappings only; logo images are not licensed by tvlogo.monster)"
}

404 Key unknown or no logo

{
  "key": "zzznonexist",
  "found": false,
  "image_url": null,
  "error": "not_found",
  "detail": "No channel, feed, station or name matches this key.",
  "trademark_note": "..."
}

410 Logo removed
429 Rate limited; see Retry-After
422 Validation Error

GET https://api.tvlogo.monster/v1/logo?key=CTV.ca%40CKYDT&mode=national&size=128

GET /v1/search

Find channels by name, id or call sign (max 20)

Parameter	Type	Values · default
q required query	string min len 1, max len 100
limit query	integer min 1, max 20	default 12
mode query	string	`local` `national` default "local"
theme query	string	`default` `dark` `light` `mono` default "default"
size query	string	`64` `128` `256` `512` default "128"

Responses

200 Successful Response
422 Validation Error

GET https://api.tvlogo.monster/v1/search?q=global&limit=5

GET /v1/stations

Find stations by place, distance, province, city, type, class or affiliate

Parameter	Type	Values · default	Description
near query	string	default ""	Centre point as lat,lon in decimal degrees (WGS84), e.g. 49.8951,-97.1384
radius_km query	string	default ""	Search radius around near, km (default 50, max 1000); distance is great-circle (haversine)
country query	string	default ""	ISO 3166-1 alpha-2 country; only CA has stations today
province query	string	default ""	2-letter province/territory code, e.g. MB, QC
city query	string	default ""	Town or city of the transmitter (case-, accent- and punctuation-insensitive)
q query	string max len 100	default ""	Optional text matched inside call sign, name or town
type query	string	`all` `main` `rebroadcaster` default "all"	main = originating transmitters, rebroadcaster = repeaters, all
class query	string max len 100	default ""	Licence/service class, one or more comma-separated: full_power, class_a, low_power (US LPTV; CA ISED class LP/VLP), translator (US translators, CA rebroadcasters). Canada has no class_a. Unknown values give 422. See /v1/classes for counts
affiliate query	string	default ""	Network or brand slug or name (ctv, global, citytv, cbc, ici-radio-canada, tva, noovo, independent...); see /v1/affiliates
has_logo query	string	`true` `false` `any` default "true"	true (default, like the map) = only stations with a served logo for the selected mode; false = only those without; any
sort query	string	`distance` `name` `call_sign` default ""	distance (default with near), name (default otherwise) or call_sign
limit query	string	default "20"	Rows per page, 1..100
cursor query	string max len 200	default ""	next_cursor from the previous page
mode query	string	`local` `national` default "local"	local = the station's own logo, falling back to brand -> network -> channel. national = the network logo for every affiliate.
theme query	string	`default` `dark` `light` `mono` default "default"	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 query	string	`current` `historic` default "current"	current = the logo in use now (new). historic = an older design (old) when we have one, else current.
size query	string	`64` `128` `256` `512` default "128"	Square PNG size in pixels (transparent canvas). All sizes are pre-rendered on i.tvlogo.monster.

Responses

200 Matching transmitters (paged; next_cursor is null on the last page)
422 Invalid filter (detail says which)
429 Rate limited; see Retry-After

GET https://api.tvlogo.monster/v1/stations

GET /v1/affiliates

Affiliate values for /v1/stations with station counts

Parameter	Type	Values · default	Description
country query	string	default ""	ISO country filter, e.g. CA
has_logo query	string	`true` `false` `any` default "true"	count only stations with (true) / without (false) a logo, or any
mode query	string	`local` `national` default "local"	mode used for has_logo

Responses

200 Successful Response
422 Validation Error

GET https://api.tvlogo.monster/v1/affiliates

GET /v1/classes

Licence/service class values for /v1/stations with station counts

Parameter	Type	Values · default	Description
country query	string	default ""	ISO country filter, e.g. CA
has_logo query	string	`true` `false` `any` default "true"	count only stations with (true) / without (false) a logo, or any
mode query	string	`local` `national` default "local"	mode used for has_logo

Responses

200 Successful Response
422 Validation Error

GET https://api.tvlogo.monster/v1/classes

GET /v1/params

Lookup parameters, values and defaults

Responses

200 Successful Response

GET https://api.tvlogo.monster/v1/params

GET /v1/version

Deployed app version: package version, git commit, deploy time

Responses

200 Successful Response

GET https://api.tvlogo.monster/v1/version

GET /v1/stats

Catalogue counts and API usage (cached 60 s)

Responses

200 Successful Response

GET https://api.tvlogo.monster/v1/stats

Image URLs

image_url points at https://i.tvlogo.monster/<id>.png (512 px). Every logo is pre-rendered at other sizes: <id>-64.png, <id>-128.png, <id>-256.png. Images are immutable and cacheable; ids change when a logo changes.