This is a google script that fetches information about TV Shows, and will set calendar events in your Google Calendar for air dates of your favourite TV Shows. The script will find the time of day the show airs as well.
If the date and time cannot be found for a particular show, an email will be sent to you to warn you that this happened. A list of the episodes that have been found to be null will be held in the fifth column of the spreadsheet. The script will continue to check these episodes until the script removes them (which only happens when a time stamp has been found for it). You may choose to remove them yourself by manually editing the cells if you feel the need to do so.
The master
branch will be considered the stable branch. The dev
branch will
be used to develop and do initial testing. The dev
branch should not be used.
The testing
branch is code that I consider done and in a working state, but I
have not tested the code to the point that it should be in master. For this
reason testing
branch can be used for if you so choose, but do so at your own
risk.
This will be a step by step guide to start using the script:
Open you Google Drive, and create a new Google Script file by clicking New -> more -> Google Apps Script
. Call it whatever you want, and just copy the
contents of add-event-to-calendar.gs
to this new file. You can bury it in any
folder you want, it doesn't care where it goes (the *.ts
file is for
development only and will not work directly with google script).
In your Google Drive, create a new spreadsheet and call it whatever you want. We will use this spreadsheet to start adding TV Shows to. As a start, put the name of a TV show into cell B1. Note that the "B" column is where all the TV show names will be. Column "C" will be used by the script to save how many episodes the script knows about already. For example, if the script knows of 40 episodes, but only 40 episodes are still known, the script won't do anything for that show until a new episode becomes known.
Column A
is used to hold the unique Show ID that TVMaze uses. This value will
be found automatically if possible using just the TV Show name that you specify.
If The script has a hard time finding out what TV Show to pick given just the
name you provide, it will email you a list of the TV Shows that it thinks you
might be referring to and it will provide you with the unique ID of each, along
with a URL to go and check to see which show is the one you want. Once you have
chosen the one you want, manually fill in column A
with the unique ID.
This Column Holds the Names of the shows. This is (almost always) the only column that you will have to edit.
Holds the Number of episodes that the script currently knows about for that TV show. This is automatically updated and initialized, so you will probably never have to do anything with this.
Holds the current state of the show (ie. Running, ended etc). This is also automatically initialized and updated.
Holds the numbers of episodes that did not have an airtime provided the last time that the script ran. This is automatically initialized and updated as well. This column exists so that the script knows to go back and check these previous episodes as well as the new ones.
Column G
is currently only used for cell G1
which stores the commit hash
that was found to be the most recent commit the last time the script ran. The
script uses this value to check to see if an update has been made to the script
since the last time you ran the script.
Now open the script from the first step. There is a line at the top of the file like this:
var SPREADSHEET_ID = "FILL THIS"
Change the FILL THIS
to the id of the spreadsheet you made in the previous
step. The id is found in the URL of the spreadsheet. If the spreadsheet has this
URL:
docs.google.com/spreadsheets/d/1RSklW9SKI535TG0LnH9cjU2c3spLtnbPBAKWahUWO7I/edit#gid=0
Then 1RSklW9SKI535TG0LnH9cjU2c3spLtnbPBAKWahUWO7I
is your id, so the
spreadsheet_id
variable changes to this:
var SPREADSHEET_ID = "1RSklW9SKI535TG0LnH9cjU2c3spLtnbPBAKWahUWO7I"
Now make sure that the script is saved. And run the script by pressing Run -> run
. Google will ask you about some permissions such as asking if it is okay
for the script to use spreadsheets and stuff like that. You have to say yes or
the script won't run. If you added something to your sheet earlier, we should
now have a calendar entry somewhere for that show, as long as it has an upcoming
episode. If you don't have a calendar entry, check the spreadsheet to see of the
"C" column was populated with a number. If it wasn't, file an issue. If it is
populated, go to your Calendar and do a search. If nothing appears, it probably
means there is no known upcoming episode for the show.
Finally, while still inside the script, at the top of the screen click:
Resources -> Current Project's Triggers
. Now click the blue text that says No triggers set up. Click here to add one now
.
For the drop down menu under "Run" make sure you select "run". This runs the "run" function inside the script. For events, you can select any type of trigger you want. This will determine how often the script is run automatically.
From this there is also a notifications
button. If you set this up, the script
will email you if it fails for some reason.
Now we are done. You will never need to go back to the script. If you want to ever add or delete a show from being searched for, just edit the spreadsheet file.
If you want to get a newer version of this script remove all the code from the current script you have, while saving the variables at the top of the code such as your spreadsheet id.
Copy all of the new code into your current script (which is now empty) and replace the variables at the top with your settings.
Check to see if the new code has a new variable at the top of the code. If you are unsure of what a variable is for or the possible options you can give, then see below in the section "Configuration Variables".
Once you have filled in the variables, save the file and do a manual run. This will check to see if the script now requires new permissions for newly added features. In order to continue accept the new requirements.
All variables must contain a value of some kind.
This is a string that comes from the URL of the spreadsheet you will use to
store your tv shows. For example, if your spreadsheet has the URL
https://docs.google.com/spreadsheets/d/1RSklW9SKI535TG0LnH9cjU2c3spLtnbPBAKWahUWO7I/edit#gid=0
,
then your SPREADSHEET_ID
is "1RSklW9SKI535TG0LnH9cjU2c3spLtnbPBAKWahUWO7I"
,
with the quotes included.
This is essential in order to get the script to work.
This is a variable that controls if you get email notifications for a status
change of a TV Show. For example, if you are following a TV Show, and it changes
from running
to ended
, you will get a email notification saying that that TV
Show has now ended.
The default setting is false
.
var GET_STATUS_CHANGE_ALERT = true
means that you will receive the email
notification when this occurs.
var GET_STATUS_CHANGE_ALERT = false
means that you will NOT receive the email
notification when this occurs.
This variable tells the script what calendar it should use.
The default setting is ""
.
var CALENDAR_ID = ""
or var calendar_id = null
means that the script will
use the default calendar that is setup (by default, this is the main calendar
that comes with your account).
var CALENDAR_ID = "calendarid"
specifies to use a specific calendar based on
the id. For this example my id is calendarid
. To find your calendar id, go to
your calendars. On the left side will be a list of calendars that you have.
Hover over the calendar you want and click the little arrow that shows up to the
right of the calendar name then select calendar settings. On this page you will
see Calendar ID: someid
where someid
is your calendar id. Now copy this
value and put it into the script as the above variable.
This variable tells the script if you want to get emailed log reports.
The default setting is false
.
var DEBUG = true
means that you want to get emails with the logs for
every execution of the script.
var DEBUG = false
means that you do NOT want to get emails with the logs
at all.
This variable tells the script if you want to get emailed every time a new episode is added to your calendar. It will give you the name of the show, and the start date and time of that episode. All additions for that execution of the script will be in the same email.
The default setting is false
.
var ADDED_EPISODE_ALERT = true
means that you want to get the emails.
var ADDED_EPISODE_ALERT = false
means that you do NOT want to get the emails.
This variable tells the script what label to look for in your gmail for adding new episodes.
The script will check your inbox for messages with a label on them that matches
the variable MYLABEL
. If it does, it checks takes the body of the email and
assumes that it is a newline separated list of TV Show titles (ie. Your email is
a list of TV Show titles with a new title on each line). It will then take those
titles, and append them to your spreadsheet for you as long as that TV show does
not already exist in the sheet (the check is case insensitive, so a TV Show
named Suits
and suits
are seen as the same. Any other difference in
spelling, spelling or other characters will be treated as a new show).
The easiest way to make assign labels automatically is to setup a filter in gmail.
-
Go to your gmail inbox.
-
Press the gear icon on the right and select
Settings
. -
Select the tab at the top labelled
Filters and Blocked Addresses
. -
Click the button that says
Create a new filter
. -
Select the criteria that you want to match then press the button that says
Create filter with this search
(The button is in the bottom right of the window that pops up) (For me, I selected to specify thatFrom
should only be my email address, andsubject
isTV Shows: Add to Calendar
. This filter will then be triggered every time I send myself an email from my own email with the subjectTV Shows: Add to Calendar
). -
On the next screen check the box for
Apply the label:
and then select the label that you defined by the variableMYLABEL
. If you haven't already created this label, select the button to create a new label. -
Select
Create Filter
. -
Make sure that the label is defined in the script, and that is all that needs to be done. The email you send yourself will be deleted by the script once it is read, so do not delete these emails manually.
The default setting is "TV Show Script"
.
This variable tells the script if you want the update function to run automatically when you run your script. When the update script is run you will get a email if an update has happened since the last time the script ran. You will not receive an email at any other time.
Note that this will NOT update the script. It will just warn you of updates that have occurred.
The default setting is true
.
var SCRIPT_AUTO_UPDATE_CHECK = true
Means to check for updates automatically before
looking for TV Shows.
var SCRIPT_AUTO_UPDATE_CHECK = false
Means that the script will never automatically
check for updates for you. So you will need to manually run the
check_for_updates
function in order to get updates.
NOTE: This variable has NO effect if auto_update_check
is set to false
This variable tells the script what branch to check for updates. It will use this to see if any new commits have come in since the last time the update function was run.
The default setting is "master"
.
var BRANCH_TO_CHECK_FOR_UPDATES = "master"
var BRANCH_TO_CHECK_FOR_UPDATES = "testing"
var BRANCH_TO_CHECK_FOR_UPDATES = "dev"
NOTE: This variable has NO effect if SCRIPT_AUTO_UPDATE_CHECK
is set to false
This variable holds the value of your Github API Token which will ONLY be used for the purpose of checking for updates. The Github API does not require a token, but you will be subject to rate limiting if you don't. As a result, if you do not provide a token to this script, you may find that you get errors in your script because the API didn't return anything. That being said, it is up to you whether or not you want to provide a token. The script will work whether you provide a token or leave the string empty.
First, you need a Github Account. If you do not have one, then register for one. Once you have an account:
- Login
- Click your profile picture in the top right corner of the page
- Select
Settings
from the drop down - In the left pane select
Developer Settings
- In the left pane select
Personal Access Tokens
- Click
Generate new token
- Give a description for the token.
- Below that are scopes. We do NOT need any of them, so leave them all
unchecked and click
Generate Token
The next page shows the token. Use this as your token. Note that you will never be able to see that token again, so copy it there and put it into the script right away. If you lose the token somehow that is not big deal. Just generate a new one with the above steps and delete your old token.
The default setting is ""
which means that NO token will be used
var BRANCH_TO_CHECK_FOR_UPDATES = ""
If 123456
is your token:
var BRANCH_TO_CHECK_FOR_UPDATES = "123456"
Changing the "B" column is perfectly okay, since this is the column you will use to tell the script what shows you want. You can freely add and delete new shows as you choose (Deleting a show consists of just deleting that whole row).
If you change data in any of the other columns and if it isn't too late to undo what you just did, then do that.
Otherwise you can just make the changed cells blank. A blank cell is interpreted as an undefined value and the script will create a starting value, as if it was the first time it was populating that cell.
Development is to be done in the TypesScript file using the provided Makefile for compilation.
In order to compile this script you need the Google Apps Script TypeScript type definitions which can be installed with this command:
npm install --save @types/google-apps-script
The header.gs file is just what the top of the final *.gs
file should look
like. I made the decision to remove empty space and comments in the compiled
version but it is still important to have comments for the top part where the
config variables are.
tvmaze.com
for the amazingly easy to use API to gather TV Show data.