{"openapi":"3.1.0","info":{"title":"tvlogo.monster API","description":"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.\n\n**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).\n\n**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","contact":{"name":"tvlogo.monster","url":"https://search.tvlogo.monster/about"},"license":{"name":"Metadata: CC BY 4.0 (logo images excluded)","url":"https://search.tvlogo.monster/legal"},"version":"0.2.0"},"paths":{"/v1/logo":{"get":{"tags":["lookup"],"summary":"Resolve one key to one logo","operationId":"v1_logo_v1_logo_get","parameters":[{"name":"key","in":"query","required":true,"schema":{"type":"string","maxLength":200,"description":"tvg-id (CTV.ca@CKYDT), epg.monster id (CTV.Winnipeg.ca), call sign (CKY-DT) or channel name (CTV Winnipeg)","title":"Key"},"description":"tvg-id (CTV.ca@CKYDT), epg.monster id (CTV.Winnipeg.ca), call sign (CKY-DT) or channel name (CTV Winnipeg)"},{"name":"namespace","in":"query","required":false,"schema":{"type":"string","description":"Which id system the key belongs to. auto tries tvg-id, epg.monster id, call sign, then channel name.","enum":["auto","iptv-org","epg.monster","call_sign","name"],"default":"auto","title":"Namespace"},"description":"Which id system the key belongs to. auto tries tvg-id, epg.monster id, call sign, then channel name."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","description":"local = the station's own logo, falling back to brand -> network -> channel. national = the network logo for every affiliate.","enum":["local","national"],"default":"local","title":"Mode"},"description":"local = the station's own logo, falling back to brand -> network -> channel. national = the network logo for every affiliate."},{"name":"theme","in":"query","required":false,"schema":{"type":"string","description":"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).","enum":["default","dark","light","mono"],"default":"default","title":"Theme"},"description":"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)."},{"name":"era","in":"query","required":false,"schema":{"type":"string","description":"current = the logo in use now (new). historic = an older design (old) when we have one, else current.","enum":["current","historic"],"default":"current","title":"Era"},"description":"current = the logo in use now (new). historic = an older design (old) when we have one, else current."},{"name":"size","in":"query","required":false,"schema":{"type":"string","description":"Square PNG size in pixels (transparent canvas). All sizes are pre-rendered on i.tvlogo.monster.","enum":["64","128","256","512"],"default":"512","title":"Size"},"description":"Square PNG size in pixels (transparent canvas). All sizes are pre-rendered on i.tvlogo.monster."},{"name":"redirect","in":"query","required":false,"schema":{"type":"boolean","description":"302 straight to the PNG instead of JSON (handy as tvg-logo in M3U playlists)","default":false,"title":"Redirect"},"description":"302 straight to the PNG instead of JSON (handy as tvg-logo in M3U playlists)"}],"responses":{"200":{"description":"Logo found (or key known but no logo: found=false, 404)","content":{"application/json":{"schema":{}}}},"404":{"description":"Key unknown or no logo"},"410":{"description":"Logo removed"},"429":{"description":"Rate limited; see Retry-After"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/search":{"get":{"tags":["lookup"],"summary":"Find channels by name, id or call sign (max 20)","operationId":"v1_search_v1_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":12,"title":"Limit"}},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["local","national"],"default":"local","title":"Mode"}},{"name":"theme","in":"query","required":false,"schema":{"type":"string","enum":["default","dark","light","mono"],"default":"default","title":"Theme"}},{"name":"size","in":"query","required":false,"schema":{"type":"string","enum":["64","128","256","512"],"default":"128","title":"Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stations":{"get":{"tags":["stations"],"summary":"Find stations by place, distance, province, city, type, class or affiliate","operationId":"v1_stations_v1_stations_get","parameters":[{"name":"near","in":"query","required":false,"schema":{"type":"string","description":"Centre point as lat,lon in decimal degrees (WGS84), e.g. 49.8951,-97.1384","default":"","title":"Near"},"description":"Centre point as lat,lon in decimal degrees (WGS84), e.g. 49.8951,-97.1384"},{"name":"radius_km","in":"query","required":false,"schema":{"type":"string","description":"Search radius around near, km (default 50, max 1000); distance is great-circle (haversine)","default":"","title":"Radius Km"},"description":"Search radius around near, km (default 50, max 1000); distance is great-circle (haversine)"},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"ISO 3166-1 alpha-2 country; only CA has stations today","default":"","title":"Country"},"description":"ISO 3166-1 alpha-2 country; only CA has stations today"},{"name":"province","in":"query","required":false,"schema":{"type":"string","description":"2-letter province/territory code, e.g. MB, QC","default":"","title":"Province"},"description":"2-letter province/territory code, e.g. MB, QC"},{"name":"city","in":"query","required":false,"schema":{"type":"string","description":"Town or city of the transmitter (case-, accent- and punctuation-insensitive)","default":"","title":"City"},"description":"Town or city of the transmitter (case-, accent- and punctuation-insensitive)"},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100,"description":"Optional text matched inside call sign, name or town","default":"","title":"Q"},"description":"Optional text matched inside call sign, name or town"},{"name":"type","in":"query","required":false,"schema":{"type":"string","description":"main = originating transmitters, rebroadcaster = repeaters, all","enum":["all","main","rebroadcaster"],"default":"all","title":"Type"},"description":"main = originating transmitters, rebroadcaster = repeaters, all"},{"name":"class","in":"query","required":false,"schema":{"type":"string","maxLength":100,"description":"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","examples":["full_power","full_power,low_power"],"default":"","title":"Class"},"description":"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"},{"name":"affiliate","in":"query","required":false,"schema":{"type":"string","description":"Network or brand slug or name (ctv, global, citytv, cbc, ici-radio-canada, tva, noovo, independent...); see /v1/affiliates","default":"","title":"Affiliate"},"description":"Network or brand slug or name (ctv, global, citytv, cbc, ici-radio-canada, tva, noovo, independent...); see /v1/affiliates"},{"name":"has_logo","in":"query","required":false,"schema":{"type":"string","description":"true (default, like the map) = only stations with a served logo for the selected mode; false = only those without; any","enum":["true","false","any"],"default":"true","title":"Has Logo"},"description":"true (default, like the map) = only stations with a served logo for the selected mode; false = only those without; any"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"distance (default with near), name (default otherwise) or call_sign","enum":["distance","name","call_sign"],"default":"","title":"Sort"},"description":"distance (default with near), name (default otherwise) or call_sign"},{"name":"limit","in":"query","required":false,"schema":{"type":"string","description":"Rows per page, 1..100","default":"20","title":"Limit"},"description":"Rows per page, 1..100"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"next_cursor from the previous page","default":"","title":"Cursor"},"description":"next_cursor from the previous page"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","description":"local = the station's own logo, falling back to brand -> network -> channel. national = the network logo for every affiliate.","enum":["local","national"],"default":"local","title":"Mode"},"description":"local = the station's own logo, falling back to brand -> network -> channel. national = the network logo for every affiliate."},{"name":"theme","in":"query","required":false,"schema":{"type":"string","description":"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).","enum":["default","dark","light","mono"],"default":"default","title":"Theme"},"description":"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)."},{"name":"era","in":"query","required":false,"schema":{"type":"string","description":"current = the logo in use now (new). historic = an older design (old) when we have one, else current.","enum":["current","historic"],"default":"current","title":"Era"},"description":"current = the logo in use now (new). historic = an older design (old) when we have one, else current."},{"name":"size","in":"query","required":false,"schema":{"type":"string","description":"Square PNG size in pixels (transparent canvas). All sizes are pre-rendered on i.tvlogo.monster.","enum":["64","128","256","512"],"default":"128","title":"Size"},"description":"Square PNG size in pixels (transparent canvas). All sizes are pre-rendered on i.tvlogo.monster."}],"responses":{"200":{"description":"Matching transmitters (paged; next_cursor is null on the last page)","content":{"application/json":{"schema":{}}}},"422":{"description":"Invalid filter (detail says which)"},"429":{"description":"Rate limited; see Retry-After"}}}},"/v1/affiliates":{"get":{"tags":["stations"],"summary":"Affiliate values for /v1/stations with station counts","operationId":"v1_affiliates_v1_affiliates_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"ISO country filter, e.g. CA","default":"","title":"Country"},"description":"ISO country filter, e.g. CA"},{"name":"has_logo","in":"query","required":false,"schema":{"type":"string","description":"count only stations with (true) / without (false) a logo, or any","enum":["true","false","any"],"default":"true","title":"Has Logo"},"description":"count only stations with (true) / without (false) a logo, or any"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","description":"mode used for has_logo","enum":["local","national"],"default":"local","title":"Mode"},"description":"mode used for has_logo"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/classes":{"get":{"tags":["stations"],"summary":"Licence/service class values for /v1/stations with station counts","operationId":"v1_classes_v1_classes_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"ISO country filter, e.g. CA","default":"","title":"Country"},"description":"ISO country filter, e.g. CA"},{"name":"has_logo","in":"query","required":false,"schema":{"type":"string","description":"count only stations with (true) / without (false) a logo, or any","enum":["true","false","any"],"default":"true","title":"Has Logo"},"description":"count only stations with (true) / without (false) a logo, or any"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","description":"mode used for has_logo","enum":["local","national"],"default":"local","title":"Mode"},"description":"mode used for has_logo"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/params":{"get":{"tags":["meta"],"summary":"Lookup parameters, values and defaults","operationId":"v1_params_v1_params_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/version":{"get":{"tags":["meta"],"summary":"Deployed app version: package version, git commit, deploy time","operationId":"v1_version_v1_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/stats":{"get":{"tags":["meta"],"summary":"Catalogue counts and API usage (cached 60 s)","operationId":"v1_stats_v1_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}