The Notion API | Using Python to access your Notion workspace

welcome back to another video so if you're at all interested in productivity or note-taking or anything like that you may well have heard of an app called notion now notion is as it says here and all in one workspace and people use it for all kinds of things it's great for collaboration but it's great to use on your own for uh organizing things it's got you can take notes but you can also then link those notes to kind of databases and to calendars and make kanban boards all kinds of things you can do with notion and because of that it's got a lot of popularity you see people on youtube and on the internet generally using notion to organize their life now one thing that the people who use notion quite a lot have been asking for for quite a long time is access to an api so as they can automate some of the things in notion even on the notion pricing page it says the content api is coming soon so they've had it on their roadmap for a while and they know that people want it and as of last week the notion api is now in public beta so what i thought i'd do in today's video is talk through how you connect to the notion api authenticate against it and do your basic crud operations and that is create read update and delete records within notion using python so with any api there's normally a page for developers which will give you some instructions and references about how to get started how to connect to the api and then a reference for what you can do to go into more detail so this is the same notion itself has got the url of notion.so the notion api documentation is developers.notion.com and here on that page we can see straight away there's a break button that says get started so we're going to click on that and see where to go from there so here we are on the getting started page now before i get cracking this is not meant to be a video which is going to go into every single detail about what you have to do over on the side you've got a page for authorization which goes into great detail on all the different authorization types grant accesses limitations blah blah blah i'm not going to go into all that it's an api which has got a lot of information about it and there's a lot of information on here i'm not going to go into all of it what i'm going to do today is just show you how to connect to notion and authenticate yourself and then use that authentication to make a number of requests so we're going to create an integration for our notion workspace what the integration is basically going to do it's almost like a permissions record which will give us a token a unique token that we can use in our code to make requests which will allow us to read and write to the database so then we're going to create a new database notion and we'll use the integration to grant permission to access it this probably doesn't make a lot of sense whilst we're reading out so i think probably what we'll do is just get into the code and see how it works so before we start doing any code then we need to do some stuff in notion first so if we look at the getting started screen um then i'm going to ignore that before we begin bit because i'm using an individual user so i am the admin user i don't need to do anything else if i was an admin and i had an organization with multiple users then okay i probably have to do something different but i haven't and i'm not so this is a simple tutorial so create a new integration in another browser window open your integrations okay where are the integrations use the button to create a new integration and give your integration a name so this is choosing vacation planner submit to create the integration all right okay let's try something like that then okay so it says to create a new integration and i've got to go to the integration section so where is that i think it'll probably be under settings and members so let's go to there and here right at the bottom your integrations fantastic there's no integration develop your own integrations now here we go i'm going to create a new integration and we're going to call this automation integration because that's really what we're doing looking to do it for okay so we don't need a logo to go with this i don't think and i'm going to submit that and there we go what's it done it's given us a secret fantastic internal integration token and if i click on show it'll give me that secret i can copy that to the clipboard and i can put that in my code right so this is internal integration or a public integration we're just going to go for this at the moment that's the default that's been setting up i just want to change a database that i'm going to set up all good if we go back to integrations page here we go is automation integration lovely the next thing we have to do is share a database with your integration okay what does that mean what we need to do is go and insert a new database what i'd quite like to do is just add a page which is going to be we're going to call this book details yeah we're just going to create a table my i'm going to have a full page table because in here it says start from a new existing page in your workspace and insert a new database by typing typing forward slash table and selecting a full page table so that's what we've done here and there we go really really naf example database but it's going to be fine so we want to put some details in here brilliant so we've just got this basic database which has got which is called book details and it's got a series of attributes about that book all right so it's got the title which is catch 22 the author is joseph heller and the status is published the next thing we have to do going back to the getting started page is we have to share this page with the integration that we created because the integration that we've created has an access token and if we allow this page to be seen by that integration then that means that authentication token will be able to be used to change this database automatically so if we go to share and we'll go to add people emails groups or integrations then you can see our integration is there automation integration so if we click that and then click invite and we'll see automation integration has got edit privileges for this page fantastic okay so we've set up an integration and then we've set up a database called book details with a load of information in it and then we've allowed the integration to see this database so i think that's probably all we have to do at the moment in notion itself the next thing that's going to happen is it says here that we're going to add an item to a database so this is using curl so this is doing it from a terminal window or the command line we don't want to do that because we want to do this using python so in that case what i'm going to do is i'm going to move away from the getting started guide and go to the api reference and see what information is in here down the side here it's got introduction authentication a lot of information we've done some of those things which is fine then down the side it's got database pages blocks and users so just quickly it's worth pointing out that the structure that notion uses and the naming conventions that it uses this is a database according to notion okay now each row in this database i would call that a row but notion doesn't do that notion calls all these rows pages so title catch 22 that's a page author and joseph heller that's a page status and published that's a page it's worth knowing that there are other terms that they use like blocks uh and users mean users is pretty self-explanatory but we're not doing anything which is outside of our user at the moment so we don't need to worry about that blocks i'm not going to go into that i'm just going to deal with databases and pages all we want to do is retrieve a page create a page and you'll notice here there's actually no no option to delete a page so i know at the start i said i was going to do create read update and delete the delete you can't do notion won't let you do that in the api and i think generally when you're doing anything automated deleting stuff is a bad idea if you want to delete anything it's probably worth having something having another value here saying whether the status is active or not and then that and if you want to delete something then rather than actually delete it what you can do is you can say so this is going to be status and this can be active and this can be active and this can be active rather than going through and deleting anything what you'd actually do is just go through and just change the status of it so you update it rather than delete it that's the that's the trick for me anyway not least because notion won't actually let you delete anything at the moment anyway but the first thing we're going to do is look at the database because what you can do is you can retrieve a database and query a database if you retrieve a database then all it's going to do is going to give you the headline details of that so what the database name is what you'll want to do to get all the information the database back will be to query the database so let's start with retrieving it and then we can take it from there so again if we look at retrieving a database for example over here it's got the curl request which you'd have to make but over here it's actually on the on this side it's got the api url so it's got the method which is get and it's got the url which is this here and then some information about what the database id is so let's do that let's try and retrieve a database and we're going to go into python and have a look at that now so here we are i've set up a project quickly in and this is vs code we're going to need to do some imports first um so we're going to need to see requests and we're going to need to do json what if we get back from the api it's going to be a json object request itself is just the python package which you'd have to install to be able to make any requests to an api or to another url an external resource so if you haven't got requests and install it [Music] you do that by doing pip3 install requests and my one's already there we're going to need some basic information to start with token and we're going to need a database id so let's go and get those if we go back to the getting started page um then down further down where it says share database with your integration it gives you a bit of information on how to get the database id so it says here before moving on you need the idea of the database you just created this is our database we just created and it says here that if you're using notion in the browser which we are then if you look at the url then this here between that last backslash and the question mark is the database id so let's go and get that database id so here we are notion.so and i can see that is going to be our database id so let's go and just copy that into python and then the other thing we're going to need is a token so here's our integration and we can go and copy internal integration token which is this here we'll copy the token and then we're going to go and pop that in here so there we go we've got our token we've got our database id in order to do this i'm going to set up some functions so because we're going to want to do a number of things so what we're going to have is a read database function and then we're going to have a create page function and then we'll also have an update page function as well the first thing we're going to do we want to try and read this database i think for my purposes if i'm going to use the notion api reading the database is the thing i'm probably going to do most often and when i say read the database i don't just mean kind of get the database title i want to get all these pages within it as well so we'll see how we do that so it's not just going to be retrieving the database i think it's going to be querying as well so but i'll show you what retrieve does just so as we've got the complete completeness um so here is our url that we're going to want to copy so i'm going to copy that and i'm going to put my read url equals that now database id here obviously isn't actually database isn't that we have to give it a database idea as well so rather than making this just a static url we're going to make it an f function and what we're going to pass it is the data base id now how do we get the database id into this function well we'll just pass it in when we call it so we're going to do data base id so that's the first thing we're going to do is there's our url now we have to call that url and see what it returns we're going to actually call the api now using the requests module the way we do that is we're going to do ris which is what we're going to assign that's what this is the res is going to be the variable that whatever is returned is stored in so requests dot request and then what we can do is we're going to put i have the method so the method is this here so it's either get or post or patch or delete as well but we don't have delete as an option so you'll see here here's all the methods and depending what we want to do we have to give it a different method but normally when you're doing a read you're doing a get so we do get and then the next thing we want to pass is the url so we've already created that url as read url and then we need to pass it some headers okay so we're gonna we say headers equals and we're going to have a variable called headers and we're just going to install that there how do we get headers in here well i think we're going to create it outside of at the start when we initialize a load of variables so we're going to have headers equals and then this is going to be a dictionary with a number of things in most importantly it's going to be we're going to have the token in there if we look here on the api reference you'll see that even when you're doing a curl reference you also have to have headers and when you're doing a curl request the headers are defined by using the minus h parameter so here we've got authorization bearer and the notion api so let's copy that out it's going to be one of our headers and we're just going to change this a little bit so we're going to authorization it's going to be formatted a little bit differently so authorization and then we'll have bearer and we'll have space and we'll just add token to that and that should give us what we need the other one which we need is this notion version that's obviously something we need to pass so let's just copy that see if it works this is a brand new api and so when you're trying to figure it out you do have to do a little bit of problem solving in order to figure out how these things work one good way to do that is to actually copy all these things into an api tool like postman or something like that i'm just doing it here and we'll should be able to see the results um so here we we've created our headers which is a good start i'm going to pass them into the read database function as as a parameter and so now it can be used here in our read database function we've created url we've passed in the details we need the database id and the headers and we'll just see what comes back so whatever is returned from the api will be stored in res and so if we want to know whether it's been a success or not it's a http request and a successful http request has got a status 200. you'll see down here errors are going to be status 449 404 uh but we want to see status 200. we'll just do a print uh res.status code that should hopefully we're going to want to see that is a 200 status code let's just go down here call our read database and database id and headers save that and then we're just going to do python 3 main dot pi let's see what happens great we've got a status code of 200 that means there's something in there what is that going to be let's have a look so we do print raise dot text we'll see what that is brilliant look at all this we've got a load of data but it looks a little bit difficult to read i'm just going to write a bit of code to spit that out to a file okay all i've done here is um if we want to get the contents of what of res of what has been returned then we want that as kind of a json object we've just said data equals res.json and that will take it out of there and store it in data and then we can dump that in a file so i've done with open a file called db.json and it'll dump it in there so when i run this now it should create a file called db.json which it does and then if i format that document so it's a bit more structured now so you can see that this is a database here's the database id when it was created and edited and it's got the title of book details yep that's exactly what we want hasn't got a lot more than that so it's got a bit of the information about what the headings are so we've got status value and description but other than that it hasn't got any of the details in there of what uh if there's any pages everything there as well which is kind of what we want so what we'll do is rather than just querying database we're just going to add the word query on the end of that and see what that produces 400 so that's the problem now 400 means it's been an error let's see what that error says so we've made an invalid request for the url so let's see what the problem is with that the reason is i've done a get and actually to query the database you've got to do a post so the api the uh the url is correct because we just put query at the end of that database id but we've got to do a post request if we're going to read that database we're just going to do instead of get i'm going to do post and then we'll uh get rid of that and just see what it comes up with so all right so that's 200 it's been successful and if we look in db now got lots more information here so here we are so we've got our database so this is not this is a list object and it's got our page and it shows the status we've got some empty rows there then this one's got let's have a look active so this is status active and then we've got value joseph heller description author okay so we've got a lot more information here and it looks like the information that we need from the whole database which is really good now to actually get this information out of there then you'd have to uh go through and select each of the different items within this uh dictionary and then find the uh the contents key and assign it to something but as you can see we want to get every we want to get a database and every page from that database and be able to return it in some way and we have that now so that's really good so we've read the database and we've stored it next we're going to go on to create a page within that database so let's go back to our database and see that here we've got title author status all these are separate pages so we want to create a new one i don't know we might want to say give it a review so we want to say the review is excellent and the status is active so how do we do that well let's go back to getting started and see if it gives us any clues it has got a section saying add an item to a database it says here each item in the notion database is a child page we've already established that and it's got some information here about what we have to do in order to to add it so we have to pass some data to the database we have to say what the database id is and then have properties which will include some information about what we want to add let's go back into the code and try and sort that out at this point i think what i'll do is i'll write some code and then um i'll talk about it after i've written it rather than you watch me typing all the time so here we go here we are i've written some code to create a page the first thing we have to do we're going to pass the database id and the headers as we did in the previous request as well in the read request we need to create a url we need to create url um so because last time we were querying a database then we used the databases part of the api here we're creating a page so we just need to use this pages part of the api and there in the create page part of the documentation it gives you that particular url that you need to hit in order to create to create a page it also tells you the method is a post method this time again so that's fine if we go down to the actual request we'll see that it's a post request and we've passed it our create url and we've passed it headers and we've passed it data now the data is doing something with this which i've called new page data you'll see from here it is a dictionary with a couple of dictionaries inside so the first one is parent um and the parent says uh the parent of this child page is the database and the database has a database id uh which you've already passed it so i've called it that and then you'll see we have to give it a lot of information about what we want to be included for this new page and you'll see that it's got description value and status as these separate dictionaries in under properties it doesn't take a genius to figure out that those are the titles of our various columns in our database now each of these has it's a particular type of field so we know that the description field is it's a title field and the value field is text and it's actually rich text so and as is the status is also text as well when we create a new page we have to tell the api all of that so we have to say here's the description and it's a title field and the text in that title field has got content and that content is going to be review and then we're going to say and the value of review is going to be rich text fields and the text for that rich text field has content which is amazing and then we have a status field which is going to be active and that's a rich text field and we have to tell it all the same things so this stuff is it's not particularly intuitive um you have to figure all this out and it took me a while to figure it out it was quite useful to use this getting started page because it gave you a bit of the formats here but actually it's got a lot of information here over on this side because of this is all in a curl reference this doesn't always make a whole lot of sense it's difficult to read it's up to you whether you use that or not but um you've got a load of stuff here about the properties and the children and blah blah blah you've got to look through all this stuff and try it out and see what um see what happens unfortunately it's it's going to be depending on what you want to create i think once you figure it out it's fine but it can be a little bit tricky and cumbersome creating this particular object that you want to add on once you've done it once then you kind of know how to and that's the point of this video really is to try and show you i've tried to figure this out and trying to show you how you uh how how you do it or how you get started at least so in order to pass that as a date to the data we need to convert this new page data dictionary into a json object so we just dump it into this field and then we'll pass that data variable as a parameter in our requests so and again we're going to print out the status code to see make sure it's make sure it's okay i'm just going to change this to say actually you know i'll do a different way we'll keep that we'll and we'll say create page database id and it is okay and then let's run that and see what happens so that's 400 again let's see what we've done wrong and this is i mean this is it with ap when you're using an api for the first time you kind of have to do a bit of trial and error now i could make this a bit more polished and not find those errors but you kind of got to go through some of these things and it's helpful sometimes to interpret what's going on in these areas as well so what we're going to do is i've just commented out this printriz.txt now it should give us a bit more information about the error if i run this again it will tell us okay body.parent should be defined instead was undefined hmm interesting let's see if we can figure out what that is so i figured out what the problem was um it's actually a problem with the headers if we go back to the create page you'll see that i think in the when i was querying it i just had the authorization bearer token and the notion version but actually needed to kind of say the content type as well and i think it was having you know struggling with that i've just gone back to the headers and i've put in content type of applications stroke json and it's been successful and what what happens is that we've got a 200 status code which says it's successful and then we get this big object which comes back when we've made this post and it's added something to the database then what it returns is the information about that page so now it's created a new page that page has got this id um it's created this time and it's got all this information in there about it which is quite useful and now if we look at our book details database we can see there's an extra field in there an extra page in there which is review amazing active that's pretty good if we run it again for example there you go new page and there you go it's appeared again what we're going to do next is a variation on this which is going to be update as well in order to update the page um we've got the slightly different update url because we need to not only go to the pages part of the api but we need to actually tell it which page id we want to update which seems obvious really uh where do we get the page id from well there's two places earlier on when we created the whole database it returned all the pages and we got all the ids in there when we created the page earlier we got an id as part of the information that was returned when it created a new page so a new page's page id was this string here and that's the one we're going to use here so we're going to take that last record that we created and change the value of it to pretty good i think from amazing if you look um here it's a similar kind of thing we don't need to give it all of the properties of all of the different fields in that page we just need to tell them the ones which we're going to change and again we need to tell it everything so we need to say well we want to change the value and that value is a rich text field and the text of that rich text field has content which is we want to now be this and again we need to turn that update data object into a json object and then pass it to the request now you'll notice that it's not a get or a post this time it's a patch so that's what we've used as the method here we've sent it the update url the normal headers and the data which is just going to be the new value of the property which we want to change um you'll notice also in this object we don't whereas in the create page object we gave it the parent we don't need to give it a pairing this time because we've already told it which page id we're going to be updating again i think when we let's see what the response text is when it when it updates as well if it's 200 then great if it's it'll probably just give us the information of the new page i would imagine so let's clear this and then brilliant so 200 fantastic there's our page id and it looks like it's probably changed the updated day and all that kind of stuff so that's all really good now let's have a look and see what our database looks like see if it's being updated there you go so for that page that we created pretty good is the new value that's pretty useful to know so again if we wanted to delete something for example we wouldn't go in and change the value of value we'd go and change the status value so we might say we want to delete this particular page or instead of it being active we'll just change it to an active and that would be kind of a soft delete as they call it so there you have it we've got three functions a read database create page an update page they're kind of the building blocks of what you would have to what you'd be able to do as far as managing the rows within the database in notion by the api how you want to use this who knows i guess one thing i would quite like to do with this is to have it as a content management system as well like cms so you might say well we want to have a website and that website has got like a heading and a description and some calls to action things like that so you could you could you could have those items here have the values of them and you could call the notion database and have it build what's in here so rather than have to go and handle any code the code just could just get all its parameters from your notion page and that'd be quite good use for it i might have a go at that because then if you use something like nitpify net if i could then just run the python module get all the information and use a static site generator like jekyll or 11t or something like that and build the website for you but that's how you would start doing it i might do some more videos with some practical use cases on it um but until then thank you very much and i hope that you found this useful

Channel: Pretty Static

Views: 4,096

Rating: 5 out of 5

Keywords: notion, notion api, python, automation, productivity, pretty static

Id: sdn1HgxLwEg

Length: 34min 16sec (2056 seconds)

Published: Tue May 25 2021