{ "openapi": "3.1.0", "info": { "title": "TV Schedule API", "version": "1.0.0", "description": "TV listings, shows and airing patterns by country and channel. Every time is UTC." }, "servers": [ { "url": "https://api.tvschedule.org" } ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "paths": { "/v1/countries": { "get": { "operationId": "list_countries", "summary": "Every country", "description": "Every country with listings, its channel count and programmes today.", "tags": [ "Directory" ], "parameters": [], "externalDocs": { "url": "https://tvschedule.org/documentation/countries" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The two-letter country code" }, "name": { "type": "string", "description": "Its name" }, "channels": { "type": "integer", "description": "How many channels" }, "channels_on_air_today": { "type": "integer", "description": "Channels with listings today" }, "programmes_today": { "type": "integer", "description": "Programmes listed today" } } } }, { "type": "object", "properties": { "code": { "type": "string", "description": "The two-letter country code" }, "name": { "type": "string", "description": "Its name" }, "channels": { "type": "integer", "description": "How many channels" }, "channels_on_air_today": { "type": "integer", "description": "Channels with listings today" }, "programmes_today": { "type": "integer", "description": "Programmes listed today" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/countries/{cc}/channels": { "get": { "operationId": "country_channels", "summary": "A country's channels", "description": "Every channel in a country, with ids, names and categories.", "tags": [ "Directory" ], "parameters": [ { "name": "cc", "in": "path", "required": true, "description": "The country, as a two-letter code such as GB.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the page before, to read the next page.", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/country-channels" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "name": { "type": "string", "description": "Its name" }, "country": { "type": "string", "description": "The country, as a two-letter code" }, "categories": { "type": "array", "description": "Its categories" }, "in_registry": { "type": "boolean", "description": "In registry" } } } }, { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "name": { "type": "string", "description": "Its name" }, "country": { "type": "string", "description": "The country, as a two-letter code" }, "categories": { "type": "array", "description": "Its categories" }, "in_registry": { "type": "boolean", "description": "In registry" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/channels/search/{q}": { "get": { "operationId": "find_channel", "summary": "Find a channel", "description": "Find a channel by name, alias or call sign.", "tags": [ "Directory" ], "parameters": [ { "name": "q", "in": "path", "required": true, "description": "A channel name, alias or call sign, two characters or more.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Only channels or airings in this country.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/channel-search" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "name": { "type": "string", "description": "Its name" }, "country": { "type": "string", "description": "The country, as a two-letter code" }, "categories": { "type": "array", "description": "Its categories" }, "in_registry": { "type": "boolean", "description": "In registry" } } } }, { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "name": { "type": "string", "description": "Its name" }, "country": { "type": "string", "description": "The country, as a two-letter code" }, "categories": { "type": "array", "description": "Its categories" }, "in_registry": { "type": "boolean", "description": "In registry" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/channels/{id}": { "get": { "operationId": "get_channel", "summary": "One channel", "description": "One channel: names, country, languages, categories and launch year.", "tags": [ "Directory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id, from a country's channels or channel search.", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/channel" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "name": { "type": "string", "description": "Its name" }, "country": { "type": "string", "description": "The country, as a two-letter code" }, "categories": { "type": "array", "description": "Its categories" }, "owner": { "type": "string", "description": "Owner" }, "network": { "type": "string", "description": "The network it belongs to" }, "launched": { "type": "integer", "description": "The year it launched" }, "closed": { "type": "string", "description": "Closed" }, "website": { "type": "string", "description": "Website" }, "in_registry": { "type": "boolean", "description": "In registry" }, "also_known_as": { "type": "array", "description": "Also known as" }, "feeds": { "type": "integer", "description": "Feeds" } } } }, { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "name": { "type": "string", "description": "Its name" }, "country": { "type": "string", "description": "The country, as a two-letter code" }, "categories": { "type": "array", "description": "Its categories" }, "owner": { "type": "string", "description": "Owner" }, "network": { "type": "string", "description": "The network it belongs to" }, "launched": { "type": "integer", "description": "The year it launched" }, "closed": { "type": "string", "description": "Closed" }, "website": { "type": "string", "description": "Website" }, "in_registry": { "type": "boolean", "description": "In registry" }, "also_known_as": { "type": "array", "description": "Also known as" }, "feeds": { "type": "integer", "description": "Feeds" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/channels/{id}/schedule/{date}": { "get": { "operationId": "channel_schedule", "summary": "A channel's schedule", "description": "A channel's day, slot by slot, times in UTC. The date is YYYY-MM-DD, yesterday, today or tomorrow.", "tags": [ "Listings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id, from a country's channels or channel search.", "schema": { "type": "string" } }, { "name": "date", "in": "path", "required": true, "description": "The day: YYYY-MM-DD, yesterday, today or tomorrow.", "schema": { "type": "string" } }, { "name": "tz", "in": "query", "required": false, "description": "Which local day to cut, as a time zone name. Times in the answer stay UTC.", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/channel-schedule" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "channel": { "type": "string", "description": "The channel id" }, "start": { "type": "string", "description": "When it starts, UTC", "format": "date-time" }, "stop": { "type": "string", "description": "When it ends, UTC", "format": "date-time" }, "title": { "type": "string", "description": "The programme title" }, "sub_title": { "type": "string", "description": "Sub title" }, "description": { "type": "string", "description": "Description" }, "category": { "type": "array", "description": "The programme's categories" }, "episode_num": { "type": "string", "description": "Episode num" }, "lang": { "type": "string", "description": "Lang" }, "rating": { "type": "string", "description": "Rating" }, "flags": { "type": "object", "description": "new, live and repeat" }, "episode": { "type": "object", "description": "The show and episode where matched: show_id, season, number" }, "film": { "type": "string", "description": "Film" } } } }, { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "channel": { "type": "string", "description": "The channel id" }, "start": { "type": "string", "description": "When it starts, UTC", "format": "date-time" }, "stop": { "type": "string", "description": "When it ends, UTC", "format": "date-time" }, "title": { "type": "string", "description": "The programme title" }, "sub_title": { "type": "string", "description": "Sub title" }, "description": { "type": "string", "description": "Description" }, "category": { "type": "array", "description": "The programme's categories" }, "episode_num": { "type": "string", "description": "Episode num" }, "lang": { "type": "string", "description": "Lang" }, "rating": { "type": "string", "description": "Rating" }, "flags": { "type": "object", "description": "new, live and repeat" }, "episode": { "type": "object", "description": "The show and episode where matched: show_id, season, number" }, "film": { "type": "string", "description": "Film" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/countries/{cc}/schedule/{date}": { "get": { "operationId": "country_schedule", "summary": "A country's schedule", "description": "Every channel in a country for a day, 50 channels a page.", "tags": [ "Listings" ], "parameters": [ { "name": "cc", "in": "path", "required": true, "description": "The country, as a two-letter code such as GB.", "schema": { "type": "string" } }, { "name": "date", "in": "path", "required": true, "description": "The day: YYYY-MM-DD, yesterday, today or tomorrow.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the page before, to read the next page.", "schema": { "type": "string" } }, { "name": "tz", "in": "query", "required": false, "description": "Which local day to cut, as a time zone name. Times in the answer stay UTC.", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/country-schedule" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "channel": { "type": "string", "description": "The channel id" }, "start": { "type": "string", "description": "When it starts, UTC", "format": "date-time" }, "stop": { "type": "string", "description": "When it ends, UTC", "format": "date-time" }, "title": { "type": "string", "description": "The programme title" }, "sub_title": { "type": "string", "description": "Sub title" }, "description": { "type": "string", "description": "Description" }, "category": { "type": "array", "description": "The programme's categories" }, "episode_num": { "type": "string", "description": "Episode num" }, "lang": { "type": "string", "description": "Lang" }, "rating": { "type": "string", "description": "Rating" }, "flags": { "type": "object", "description": "new, live and repeat" }, "episode": { "type": "string", "description": "The show and episode where matched: show_id, season, number" }, "film": { "type": "string", "description": "Film" } } } }, { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "channel": { "type": "string", "description": "The channel id" }, "start": { "type": "string", "description": "When it starts, UTC", "format": "date-time" }, "stop": { "type": "string", "description": "When it ends, UTC", "format": "date-time" }, "title": { "type": "string", "description": "The programme title" }, "sub_title": { "type": "string", "description": "Sub title" }, "description": { "type": "string", "description": "Description" }, "category": { "type": "array", "description": "The programme's categories" }, "episode_num": { "type": "string", "description": "Episode num" }, "lang": { "type": "string", "description": "Lang" }, "rating": { "type": "string", "description": "Rating" }, "flags": { "type": "object", "description": "new, live and repeat" }, "episode": { "type": "string", "description": "The show and episode where matched: show_id, season, number" }, "film": { "type": "string", "description": "Film" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/xmltv/channels/{id}": { "get": { "operationId": "xmltv", "summary": "XMLTV for a channel", "description": "A channel as an XMLTV file, today and the days ahead in your window.", "tags": [ "Listings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id, from a country's channels or channel search.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "How many days ahead to cover, within your plan.", "schema": { "type": "integer", "minimum": 1, "maximum": 7 } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/xmltv" }, "responses": { "200": { "description": "An XMLTV file", "content": { "application/xml": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/shows/search/{q}": { "get": { "operationId": "find_show", "summary": "Find a show", "description": "Find a show by any of its titles.", "tags": [ "Shows" ], "parameters": [ { "name": "q", "in": "path", "required": true, "description": "Any title of the show, two characters or more.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/show-search" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "name": { "type": "string", "description": "Its name" }, "type": { "type": "string", "description": "Type" }, "status": { "type": "string", "description": "Running or ended" }, "premiered": { "type": "string", "description": "When it first aired" }, "network": { "type": "object", "description": "The network it belongs to" } } } }, { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "name": { "type": "string", "description": "Its name" }, "type": { "type": "string", "description": "Type" }, "status": { "type": "string", "description": "Running or ended" }, "premiered": { "type": "string", "description": "When it first aired" }, "network": { "type": "object", "description": "The network it belongs to" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/shows/{id}": { "get": { "operationId": "get_show", "summary": "One show", "description": "One show: titles, network, genres, status and premiere.", "tags": [ "Shows" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The show id, from show search.", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/show" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "name": { "type": "string", "description": "Its name" }, "type": { "type": "string", "description": "Type" }, "status": { "type": "string", "description": "Running or ended" }, "premiered": { "type": "string", "description": "When it first aired" }, "network": { "type": "object", "description": "The network it belongs to" }, "ended": { "type": "string", "description": "Ended" }, "language": { "type": "string", "description": "Language" }, "genres": { "type": "array", "description": "Its genres" }, "runtime": { "type": "integer", "description": "Runtime" }, "country": { "type": "string", "description": "The country, as a two-letter code" }, "official_site": { "type": "string", "description": "Official site" }, "imdb": { "type": "string", "description": "Imdb" } } } }, { "type": "object", "properties": { "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "name": { "type": "string", "description": "Its name" }, "type": { "type": "string", "description": "Type" }, "status": { "type": "string", "description": "Running or ended" }, "premiered": { "type": "string", "description": "When it first aired" }, "network": { "type": "object", "description": "The network it belongs to" }, "ended": { "type": "string", "description": "Ended" }, "language": { "type": "string", "description": "Language" }, "genres": { "type": "array", "description": "Its genres" }, "runtime": { "type": "integer", "description": "Runtime" }, "country": { "type": "string", "description": "The country, as a two-letter code" }, "official_site": { "type": "string", "description": "Official site" }, "imdb": { "type": "string", "description": "Imdb" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/shows/{id}/airings": { "get": { "operationId": "show_airings", "summary": "Where a show airs", "description": "Where and when a show airs in the days ahead, first runs and repeats.", "tags": [ "Shows" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The show id, from show search.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Only channels or airings in this country.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "How many days ahead to cover, within your plan.", "schema": { "type": "integer", "minimum": 1, "maximum": 7 } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/show-airings" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string", "description": "The channel id" }, "start": { "type": "string", "description": "When it starts, UTC", "format": "date-time" }, "stop": { "type": "string", "description": "When it ends, UTC", "format": "date-time" }, "title": { "type": "string", "description": "The programme title" }, "episode": { "type": "object", "description": "The show and episode where matched: show_id, season, number" }, "flags": { "type": "object", "description": "new, live and repeat" } } } }, { "type": "object", "properties": { "channel": { "type": "string", "description": "The channel id" }, "start": { "type": "string", "description": "When it starts, UTC", "format": "date-time" }, "stop": { "type": "string", "description": "When it ends, UTC", "format": "date-time" }, "title": { "type": "string", "description": "The programme title" }, "episode": { "type": "object", "description": "The show and episode where matched: show_id, season, number" }, "flags": { "type": "object", "description": "new, live and repeat" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/shows/{id}/pattern": { "get": { "operationId": "show_pattern", "summary": "A show's airing pattern", "description": "A show's usual slot, its day by hour fingerprint and repeat share.", "tags": [ "Patterns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The show id, from show search.", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/show-pattern" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "usual": { "type": "object", "description": "Its usual slot: day, time and channel" }, "grid": { "type": "array", "description": "Airings by weekday (7 rows) and hour (24 columns), UTC" }, "main_channel": { "type": "object", "description": "The channel that airs it most" }, "airings": { "type": "integer", "description": "How many times it aired" }, "channels": { "type": "integer", "description": "How many channels" }, "repeat_share": { "type": "number", "description": "The share of airings that were repeats, 0 to 1" }, "window_days": { "type": "integer", "description": "The days counted" } } } }, { "type": "object", "properties": { "usual": { "type": "object", "description": "Its usual slot: day, time and channel" }, "grid": { "type": "array", "description": "Airings by weekday (7 rows) and hour (24 columns), UTC" }, "main_channel": { "type": "object", "description": "The channel that airs it most" }, "airings": { "type": "integer", "description": "How many times it aired" }, "channels": { "type": "integer", "description": "How many channels" }, "repeat_share": { "type": "number", "description": "The share of airings that were repeats, 0 to 1" }, "window_days": { "type": "integer", "description": "The days counted" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/shows/{id}/stats": { "get": { "operationId": "show_stats", "summary": "A show's statistics", "description": "Airing counts by channel, country and year, first and last aired.", "tags": [ "Patterns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The show id, from show search.", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/show-stats" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "airings": { "type": "integer", "description": "How many times it aired" }, "first_runs": { "type": "integer", "description": "Airings that were first runs" }, "repeats": { "type": "integer", "description": "Airings that were repeats" }, "channels": { "type": "integer", "description": "How many channels" }, "first_seen": { "type": "string", "description": "The first day in our data" }, "last_seen": { "type": "string", "description": "The latest day in our data" } } } }, { "type": "object", "properties": { "airings": { "type": "integer", "description": "How many times it aired" }, "first_runs": { "type": "integer", "description": "Airings that were first runs" }, "repeats": { "type": "integer", "description": "Airings that were repeats" }, "channels": { "type": "integer", "description": "How many channels" }, "first_seen": { "type": "string", "description": "The first day in our data" }, "last_seen": { "type": "string", "description": "The latest day in our data" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/channels/{id}/stats": { "get": { "operationId": "channel_stats", "summary": "A channel's statistics", "description": "Days held, programmes a week, genre mix and repeat share for a channel.", "tags": [ "Patterns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id, from a country's channels or channel search.", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/channel-stats" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "programmes": { "type": "integer", "description": "Programmes counted" }, "shows": { "type": "integer", "description": "Distinct shows" }, "repeat_share": { "type": "number", "description": "The share of airings that were repeats, 0 to 1" }, "top_genres": { "type": "array", "description": "Its biggest genres and their share" }, "first_seen": { "type": "string", "description": "The first day in our data" }, "last_seen": { "type": "string", "description": "The latest day in our data" } } } }, { "type": "object", "properties": { "programmes": { "type": "integer", "description": "Programmes counted" }, "shows": { "type": "integer", "description": "Distinct shows" }, "repeat_share": { "type": "number", "description": "The share of airings that were repeats, 0 to 1" }, "top_genres": { "type": "array", "description": "Its biggest genres and their share" }, "first_seen": { "type": "string", "description": "The first day in our data" }, "last_seen": { "type": "string", "description": "The latest day in our data" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/countries/{cc}/most-aired": { "get": { "operationId": "most_aired", "summary": "Most aired last week", "description": "The most aired shows and films in a country last week, with the change.", "tags": [ "Patterns" ], "parameters": [ { "name": "cc", "in": "path", "required": true, "description": "The country, as a two-letter code such as GB.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/most-aired" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "description": "Its place in the chart" }, "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "kind": { "type": "string", "description": "show or film" }, "name": { "type": "string", "description": "Its name" }, "genre": { "type": "string", "description": "Its main genre" }, "airings": { "type": "integer", "description": "How many times it aired" }, "change": { "type": "integer", "description": "Places up or down on the week before" } } } }, { "type": "object", "properties": { "rank": { "type": "integer", "description": "Its place in the chart" }, "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "kind": { "type": "string", "description": "show or film" }, "name": { "type": "string", "description": "Its name" }, "genre": { "type": "string", "description": "Its main genre" }, "airings": { "type": "integer", "description": "How many times it aired" }, "change": { "type": "integer", "description": "Places up or down on the week before" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/countries/{cc}/repeats": { "get": { "operationId": "repeats", "summary": "Most repeated last week", "description": "The most repeated shows and films in a country last week.", "tags": [ "Patterns" ], "parameters": [ { "name": "cc", "in": "path", "required": true, "description": "The country, as a two-letter code such as GB.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "externalDocs": { "url": "https://tvschedule.org/documentation/repeats" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "description": "Its place in the chart" }, "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "kind": { "type": "string", "description": "show or film" }, "name": { "type": "string", "description": "Its name" }, "genre": { "type": "string", "description": "Its main genre" }, "airings": { "type": "integer", "description": "How many times it aired" }, "change": { "type": "integer", "description": "Places up or down on the week before" } } } }, { "type": "object", "properties": { "rank": { "type": "integer", "description": "Its place in the chart" }, "id": { "type": "string", "description": "Its id, stable and used by every other endpoint" }, "kind": { "type": "string", "description": "show or film" }, "name": { "type": "string", "description": "Its name" }, "genre": { "type": "string", "description": "Its main genre" }, "airings": { "type": "integer", "description": "How many times it aired" }, "change": { "type": "integer", "description": "Places up or down on the week before" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/usage": { "get": { "operationId": "check_usage", "summary": "Your usage", "description": "Your plan, calls today and this month, limits and the data window. Not counted.", "tags": [ "Account" ], "parameters": [], "externalDocs": { "url": "https://tvschedule.org/documentation/usage" }, "responses": { "200": { "description": "data and meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "plan": { "type": "string", "description": "Your plan" }, "plan_name": { "type": "string", "description": "Your plan's name" }, "key_prefix": { "type": "string", "description": "The start of the key used" }, "calls_today": { "type": "integer", "description": "Calls today, UTC" }, "calls_month": { "type": "integer", "description": "Calls this month, UTC" }, "limits": { "type": "object", "description": "per_minute, per_day and per_month for your plan" }, "resets": { "type": "object", "description": "When the minute, the day and the month reset" }, "window": { "type": "object", "description": "The listings and statistics your plan reads" } } } }, { "type": "object", "properties": { "plan": { "type": "string", "description": "Your plan" }, "plan_name": { "type": "string", "description": "Your plan's name" }, "key_prefix": { "type": "string", "description": "The start of the key used" }, "calls_today": { "type": "integer", "description": "Calls today, UTC" }, "calls_month": { "type": "integer", "description": "Calls this month, UTC" }, "limits": { "type": "object", "description": "per_minute, per_day and per_month for your plan" }, "resets": { "type": "object", "description": "When the minute, the day and the month reset" }, "window": { "type": "object", "description": "The listings and statistics your plan reads" } } } ] }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "responses": { "Error": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "upgrade_required", "not_found", "unknown_parameter", "rate_limited", "quota_exceeded", "server_error" ] }, "message": { "type": "string" }, "plan": { "type": "string" }, "docs": { "type": "string" } } } } } } } } } } }