The Complete Notion API Crash Course for Beginners

APIs (Application Programming Interfaces) are sets of tools that allow different web services to talk to each other over the HTTP protocol.

An API can allow one service to read data from another one; alternatively, it can allow one service to create new data at another service, update existing data, or even delete data.

You’ll often see another acronym used to describe these four potential operations: CRUD.

• Create
• Read
• Update
• Delete

APIs are what allow you to posts Giphy GIFs directly in Slack. They enable those awesome link previews that you can create in a Notion page. And they are the many engines under the hood of connector tools like Zapier and Make.com.

APIs typically consist of one or more URLs, to which your application can make HTTP(S) requests in order to do one or more CRUD operations. These URLs are often called endpoints.

Note: You may have a conversation in the future about APIs with a nerd who will stress that you access URIs, not URLs. The distinction really does not matter here, but here’s an article on their differences if you’re curious.

In most cases, APIs will have separate endpoints for each type of operation you can do. In other words, you’ll almost never use the same endpoint to both read data and delete data.

To see how an API actually works, let’s look at an example from PokeAPI – the API we’ll be working with later in the tutorial.

One of PokeAPI’s endpoints is the pokemon endpoint, accessible via either one of these URL schemes:

• https://pokeapi.co/api/v2/pokemon/[pokemon name]
• https://pokeapi.co/api/v2/pokemon/[pokemon number]

To access information about Charmander, you’d either use https://pokeapi.co/api/v2/pokemon/charmander or https://pokeapi.co/api/v2/pokemon/4.

Since PokeAPI doesn’t require any special kind of authentication, you can even visit these URLs in your browser. Here’s a link you can try.

However, you’ll quickly realize that visiting that URL in the browser isn’t very useful; you’re just presented with a huge string of JSON.

I’ll cover JSON more thoroughly later, but you can watch this video now if you’re curious about what it is and how it works:

However, if you make that request from a program, you can use additional code to process that JSON response and do really useful things.

For example, you could write code that goes through all that data, pulls out the Pokemon’s name, and displays it. I show this example later in this guide (click here to jump to it), so I won’t repost it here.

Of course, you can do much more than just display the Pokemon’s name. Once you have the information, you can do basically anything with it, so long as you know how to write the required code.

That’s the power of an API: It allows you to do CRUD operations, and then combine them with any sort of code you want to write. The applications are basically limitless.

To wrap up this small primer, I’ll go over the five most common HTTP methods available to you when working with APIs. You’ll see these all the time, so it’s good to be familiar with them.

• GET – used for reading data from the application. It is read-only, so it has no risk of modifying any data.
• POST – sends data to the application to create something new.
• PUT – sends data to the application to update an existing resource. Contains a full updated copy of the resource.
• PATCH – also updates an existing resource, but only contains the changes to be made instead of the entire updated resource.
• DELETE – sends an instruction to the application to delete an existing resource.

In many cases, your requests to a particular API will need to contain both the URL to be accessed and the method to be used.

For example, if you want to create a page in Notion via the API, you’ll need to access the https://api.notion.com/v1/pages endpoint using a POST request.

You’ll learn much more about APIs simply by working through this project. However, you can also get additional insight with the following resources.

First, check out Fireship’s excellent (and short) overview:

If you fancy long videos, you may also enjoy freeCodeCamp’s APIs for Beginners course (though you could also just watch the video version of this tutorial near the top of this page!

If you don’t know how to code – if you get confused and overwhelmed at most coding tutorials – I’ve been in your shoes.

At the beginning of last year (2022), I didn’t know how to code. I barely knew what an API was.

I tried to watch tutorials, but I’d get confused when the creator would throw around terms like “npm”, “node.js”, and “API endpoint” without explaining them.

Eventually, after much Googling and a lot of frustration, things started to click for me.

Hopefully I can spare you some of that frustrated Googling (Froogling?) with this tutorial.

As you’ll see later, I’ve added lots of toggles just like this one throughout the tutorial. The purpose of these is to give you an explanation for everything if you need it (and keeping these explanations in toggles lets more experienced coders skip past them easily).

However, the best piece of advice I can give you for learning how to do is this:

Run your code early and often.

The true “best” way to learn how to code is to write a lot of code and to get lots of feedback. Luckily, you get feedback pretty quickly when you’re coding; when there’s an error, it’ll be logged in your console or somewhere else.

So dive in and get your hands dirty!

This project involves working with several tools, two different APIs, and multiple JavaScript programming methods and concepts.

Here, I’ve compiled a full list of all of these things, along with some general resources you can use to learn JavaScript more comprehensively.

I encourage you to use this as a reference, but don’t let its length intimidate you! If you follow the rest of the tutorial, I’m confident that you can get the entire project working even if you don’t understand everything right away.

Once you do, you’ll be in a better position to go back, dig into these resources, and really understand how they all fit together.

Tools Used in This Project

This is a list of the specific tools and libraries we’ll use in this project. Since we’ll be building in Glitch, you don’t really need to worry about their details – Glitch will take care of most of the work for you.

• Glitch – a free platform for building websites and web apps. Includes everything – a full code editor, Node.js backend, npm package manager, terminal, and more.
• Node.js (automatically set up by Glitch) – a runtime for JavaScript. Allows you to run JavaScript code outside of the browser, effectively enabling JavaScript to be used as a back-end (server-side) language. Learn more about Node here.
• Npm (automatically set up by Glitch) – the Node Package Manager. Allows you to very easily include external code libraries in your project and use them. There are thousands of packages, including one for Notion’s API.
• PokéAPI – an open-source API that enables you to access pretty much any data related to Pokémon that you could ever want.
• Notion API – Notion’s official API, which allows you to read, write, update, and delete resources in a Notion workspace.
• Axios – a free HTTP library that works with Node.js. This is the library we’ll use to access the PokéAPI.

Note: You can also build this project on your local machine. I’m using Glitch because it keeps things extremely simple and takes care of the setup. If you want to go the local route, you’ll need a code editor like VS Code. You’ll also need to install Node.js and npm.

JavaScript Learning Resources

These free courses and general-purpose resources are great for developing a full understanding of JavaScript.

• JavaScript Algorithms and Data Structures – a full, free, and interactive JavaScript course by freeCodeCamp. This is, IMO, the best beginner resource for learning JavaScript. The course has hundreds of mini-lessons, each of which teaches a concept and then has you actually use it in the in-browser code editor. I have only done the Basic JavaScript and ES6 sections of this course, personally. You absolutely don’t need to finish the entire course to understand this tutorial.
• That Weird JavaScript Course – Fireship’s great series of YouTube videos on JavaScript. Each is super-entertaining and does a great job at explaining JavaScript at a high level.
• The Modern JavaScript Tutorial – an excellent written guide to JavaScript.
• The MDN Web Docs – the definitive technical reference for JavaScript. I’ll be linking to this many, many times in this guide.
• Beginner JavaScript Notes – a free “cliff’s notes” version of Wes Bos’ paid Beginner JavaScript course.
• JSFiddle – a tool for running small code snippets in your browser. Great for testing things out without much required overhead.

Specific Concepts

This is a list of the individual concepts and programming patterns/data structures we’ll use in this tutorial. I’ve listed the actual methods we’ll use separately below.

These have been ordered roughly by their difficulty, and I’ve included a recommended understanding level for each. This isn’t a requirement; I think you can work your way through this tutorial and refer to these concepts as you go. It’s more an indication of my own perceived understanding of each concept at the time I built this project.

Specific Methods

We’ll use several built-in JavaScript methods throughout this tutorial. Below, I’ve linked to the documentation for each one on the MDN Web Docs. These are ordered alphabetically.

• Array.prototype.find()
• Array.prototype.join()
• Array.prototype.map()
• Array.prototype.pop()
• Array.prototype.push()
• setTimeout()
• String.prototype.replace()
• String.prototype.split()
• String.prototype.substring()
• String.prototype.toUpperCase()

How to Go Further

If you finish this tutorial and want to push your skills even further, here are a few challenge ideas:

• Use the Notion API and database relations to display the evolution chain for each Pokémon.
• Display a table within each Pokémon’s page that contains each move that it can learn.
• Push the data from your Notion Pokédex to a static website (example: Daniel Shiffman’s Nature of Code site uses Notion as a CMS)

Remember that you can view this code directly on my Glitch project as well! It is located in the index-nocomments.js file.

const axios = require('axios')
const { Client } = require('@notionhq/client')


const notion = new Client({auth: process.env.NOTION_KEY})


const pokeArray = []

async function getPokemon() {
  const start = 1
  const end = 10
  for (let i = start; i <= end; i++) {
    const poke = await axios.get(`https://pokeapi.co/api/v2/pokemon/${i}`)
    .then((poke) => {
      const typesRaw = poke.data.types
      const typesArray = []
      for (let type of typesRaw) {
        const typeObj = {
          "name": type.type.name
        }
        typesArray.push(typeObj)
      }
      
      const processedName = poke.data.species.name.split(/-/).map((name) => {
        return name[0].toUpperCase() + name.substring(1);
      }).join(" ")
      .replace(/^Mr M/,"Mr. M")
      .replace(/^Mime Jr/,"Mime Jr.")
      .replace(/^Mr R/,"Mr. R")
      .replace(/mo O/,"mo-o")
      .replace(/Porygon Z/,"Porygon-Z")
      .replace(/Type Null/, "Type: Null")
      .replace(/Ho Oh/,"Ho-Oh")
      .replace(/Nidoran F/,"Nidoran♀")
      .replace(/Nidoran M/,"Nidoran♂")
      .replace(/Flabebe/,"Flabébé")
      
      const bulbURL = `https://bulbapedia.bulbagarden.net/wiki/${processedName
.replace(' ', '_')}_(Pokémon)`
      
      const sprite = (!poke.data.sprites.front_default) ? poke.data.sprites.other['official-artwork'].front_default : poke.data.sprites.front_default

      const pokeData = {
        "name": processedName,
        "number": poke.data.id,
        "types": typesArray,
        "height": poke.data.height,
        "weight": poke.data.weight,
        "hp": poke.data.stats[0].base_stat,
        "attack": poke.data.stats[1].base_stat,
        "defense": poke.data.stats[2].base_stat,
        "special-attack": poke.data.stats[3].base_stat,
        "special-defense": poke.data.stats[4].base_stat,
        "speed": poke.data.stats[5].base_stat,
        "sprite": sprite,
        "artwork": poke.data.sprites.other['official-artwork'].front_default,
        "bulbURL": bulbURL
      }
      
      console.log(`Fetched ${pokeData.name}.`)

      pokeArray.push(pokeData)
    })
    .catch((error) => {
      console.log(error)
    })
  }
  
  for (let pokemon of pokeArray) {
    const flavor = await axios.get(`https://pokeapi.co/api/v2/pokemon-species/${pokemon.number}`)
      .then((flavor) => {
        
        const flavorText = flavor.data.flavor_text_entries.find(({language: { name }}) => name === "en").flavor_text.replace(/\n|\f|\r/g, " ")
        const category = flavor.data.genera.find(({language: { name }}) => name === "en").genus
        const generation = flavor.data.generation.name.split(/-/).pop().toUpperCase()

        pokemon['flavor-text'] = flavorText
        pokemon.category = category
        pokemon.generation = generation
        
        console.log(`Fetched flavor info for ${pokemon.name}.`)
      })
      .catch((error) => {
        console.log(error)
      })
  }
  
  createNotionPage();
}

getPokemon();

const sleep = (milliseconds) => {
  return new Promise(resolve => setTimeout(resolve, milliseconds))
};

async function createNotionPage() {
  for (let pokemon of pokeArray) {
    
    const data = {
      "parent": {
        "type": "database_id",
        "database_id": process.env.NOTION_DATABASE_ID
      },
      "icon": {
        "type": "external",
        "external": {
          "url": pokemon.sprite
        }
      },
      "cover": {
        "type": "external",
        "external": {
          "url": pokemon.artwork
        }
      },
      "properties": {
        "Name": {
          "title": [
            {
              "text": {
                "content": pokemon.name
              }
            }
          ]
        },
        "Category": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": pokemon.category
              }
            }
          ]
        },
        "No": {
          "number": pokemon.number
        },
        "Type": {
          "multi_select": pokemon.types
        },
        "Generation": {
          "select": {
            "name": pokemon.generation
          }
        },
        "Sprite": {
          "files": [
            {
              "type": "external",
              "name": "Pokemon Sprite",
              "external": {
                "url": pokemon.sprite
              }
            }
          ]
        },
        "Height": { "number": pokemon.height },
        "Weight": { "number": pokemon.weight },
        "HP": { "number": pokemon.hp },
        "Attack": { "number": pokemon.attack },
        "Defense": { "number": pokemon.defense },
        "Sp. Attack": { "number": pokemon['special-attack'] },
        "Sp. Defense": { "number": pokemon['special-defense'] },
        "Speed": { "number": pokemon.speed }
      },
      "children": [
        {
          "object": "block",
          "type": "quote",
          "quote": {
            "rich_text": [
              {
                "type": "text",
                "text": {
                  "content": pokemon['flavor-text']
                }
              }
            ]
          }
        },
        {
          "object": "block",
          "type": "paragraph",
          "paragraph": {
            "rich_text": [
              {
                "type": "text",
                "text": {
                  "content": ""
                }
              }
            ]
          }
        },
        {
          "object": "block",
          "type": "paragraph",
          "paragraph": {
            "rich_text": [
              {
                "type": "text",
                "text": {
                  "content": "View This Pokémon's Entry on Bulbapedia:"
                }
              }
            ]
          }
        },
        {
          "object": "block",
          "type": "bookmark",
          "bookmark": {
            "url": pokemon.bulbURL
          }
        }
      ]
    }
    
    await sleep(300)
    
    console.log(`Sending ${pokemon.name} to Notion`)
    const response = await notion.pages.create( data )
    console.log(response)
  }
  
  console.log(`Operation complete.`)
}
Code language: JavaScript (javascript)

Remember that you can view this code directly on my Glitch project as well! It it located in the index.js file.

/* Bring in the external packages we'll be using.

Axios is an HTTP client that makes working with APIs easier: https://axios-http.com/docs/intro

Additionally, we bring in the Notion API client so we can make requests to it. */
const axios = require('axios')
const { Client } = require('@notionhq/client')

/* Create a new object 'notion' that gives our code access to the Notion credentials set up in the .env file */
const notion = new Client({auth: process.env.NOTION_KEY})

/* Create a blank array in which we'll store an object for each pokemon fetched from the PokeAPI */
const pokeArray = []

/* Create a function for making requests to the PokeAPI. We have to use an asynchronous function becuause axios.get() returns a Promise. 

Without using an async function, the rest of our code would run before axios gets a response from the PokeAPI. */
async function getPokemon() {
  
  /* Define start and end variables for the 'for' loop below. 
  
  These numbers would usually be set directly in the for loop itself, but I've made them into their own variables so you can easily tweak them. 
  
  They correspond to actual Pokemon numbers - e.g. 1 = bulbasaur. */
  const start = 1
  const end = 10
  
  /* This 'for' loop will make the first set of requests to the PokeAPI.
  
  We're using a basic 'for (let i = num)' loop because i will correspond to specific Pokemon numbers. So if you only wanted the original 151, you'd set start at 1 and end at 151. */
  for (let i = start; i <= end; i++) {
    
    /* Use the axios.get() method to make a GET request to the PokeAPI's 'pokemon' endpoint: https://pokeapi.co/docs/v2#pokemon
    
    This endpoint allows to to access MOST of the information we need. The only info we can't get from this endpoint is flavor text, generation #, and category (e.g. "Flame Pokemon"). For that info, we'll have to query the 'pokemon-species' endpoint later on. 
    
    Note how we're using a template literal in order to pass our `i` variable's value into the URL.    This is what will allow us to call PokeAPI for the correct pokemon on each run of the loop, e.g. https://pokeapi.co/api/v2/pokemon/4 (when i = 4) will get Charmander. */
    const poke = await axios.get(`https://pokeapi.co/api/v2/pokemon/${i}`)
    .then((poke) => {
      
      /* Pokemon have a variable number of types (some have 1, some have 2). The Notion API expects Multi-Select property selections to come in the form of an array of objects, so we need to create an array of objects that we can pass when we're setting the 'Type' Multi-Select property's values. 
      
      First, we store the types array from PokeAPI in the typesRaw variable. */
      const typesRaw = poke.data.types
      
      /* Now we'll create a blank array that will contain our type objects, which will be formated specifically so they'll work with the Notion  API. */
      const typesArray = []
      
      /*  Create a for...of loop that will loop through all the elements of typesRaw. 
      
      For each one, we'll create an object 'typeObj' which is formatted as needed for the Notion API, which which contains ONE of the Pokemon's types. Since the number of loop iterations is defined by the length of the typesRaw array, we'll end up with a new array (typesArray) that contains an object for each of the Pokemon's types. 
      
      E.G. - Butterfree is Bug-type and Flying-type, so its typesArray will have two elements. */
      for (let type of typesRaw) {
        const typeObj = {
          "name": type.type.name
        }
        
        /* Add the object onto the end of typesArray */
        typesArray.push(typeObj)
      }
      
      /* The PokeAPI returns very basic formatting for Pokemon names - e.g. 'Mr. Mime' is formatted as 'mr-mime'. We want to show names with proper punctuation and capitalization in Notion - e.g. 'Mr. Mime'. 
      
      This is also important for auto-generating links to Bulbapedia, where more information about each Pokemon can be found (this is a basic Pokedex that doesn't include move information, locations, etc.)
      
      To accomplish this, we're running the poke.data.species.name object through several functions. First, the split().map().join() combo capitalizes the first letter of each word - e.g. 'mr-mime' becomes 'Mr Mime'.
      
      When methods are chained like this, they are executed left-to-right. So the return value of split() is fed into map(), and map()'s return value is fed into join(). 
      
      Then, we run that result through a gauntlet of replace() calls to deal with edge case Pokemon like Type: Null, Ho-Oh, Mr. Mime, and Nidoran♀ - all of which include punctuation or symbols. Each replace() call looks for a regular expression match and replaces the first one it finds with the next argument. */
      const processedName = poke.data.species.name.split(/-/).map((name) => {
        return name[0].toUpperCase() + name.substring(1);
      }).join(" ")
      .replace(/^Mr M/,"Mr. M")
      .replace(/^Mime Jr/,"Mime Jr.")
      .replace(/^Mr R/,"Mr. R")
      .replace(/mo O/,"mo-o")
      .replace(/Porygon Z/,"Porygon-Z")
      .replace(/Type Null/, "Type: Null")
      .replace(/Ho Oh/,"Ho-Oh")
      .replace(/Nidoran F/,"Nidoran♀")
      .replace(/Nidoran M/,"Nidoran♂")
      .replace(/Flabebe/,"Flabébé")
      
      /* Define a variable that holds the bulbapedia URL for the Pokemon. Bulbapedia has a very standardized URL scheme for Pokemon, so all we need to do is pass in the processedName variable and then replace any space characters it contains with underscores. 
      
      All other special characters are left in the URL - even :,é,-,etc.
      
      Example URL: https://bulbapedia.bulbagarden.net/wiki/Mr._Mime_(Pokémon) */
      const bulbURL = `https://bulbapedia.bulbagarden.net/wiki/${processedName
.replace(' ', '_')}_(Pokémon)`
      
      /* Here we're defining a variable for the sprite using ternary syntax (? and : ) to create a conditional statement. 
      
      We need to do this because certain Gen VIII Pokemon were introduced in Pokemon Legends: Arceus and do not have a sprite. The PokeAPI has an 'official-artwork' image for EVERY Pokemon, so we'll set the value of sprite to 'official-artwork' if a 'front_default' sprite doesn't exist. 
      
      (!poke.data.sprites.front_default) is a Boolean check; if the value of this object is null, it'll evaluate to false. */
      const sprite = (!poke.data.sprites.front_default) ? poke.data.sprites.other['official-artwork'].front_default : poke.data.sprites.front_default

      
      /* Now we'll construct the object that will hold all of the data about this Pokemon. If you recall, we aren't able to pull generation, flavor text, or category from PokeAPI's 'pokemon' endpoint, so we'll add those to this object later. 
      
      For now, each object property is being set to the value of the corresponding property returned from our first PokeAPI call. 
      
      Note how ['official-artwork'] is defined differently. Property key names with dashes or spaces must be called using 'bracket notation' rather than 'dot notation'. */
      const pokeData = {
        "name": processedName,
        "number": poke.data.id,
        "types": typesArray,
        "height": poke.data.height,
        "weight": poke.data.weight,
        "hp": poke.data.stats[0].base_stat,
        "attack": poke.data.stats[1].base_stat,
        "defense": poke.data.stats[2].base_stat,
        "special-attack": poke.data.stats[3].base_stat,
        "special-defense": poke.data.stats[4].base_stat,
        "speed": poke.data.stats[5].base_stat,
        "sprite": sprite,
        "artwork": poke.data.sprites.other['official-artwork'].front_default,
        "bulbURL": bulbURL
      }
      
      /* Send a log to the console with each fetched Pokemon's name. Doing this will allow the console to show activity the whole time the script is running. Without it, you'll just see a blank spot in your console while the script takes minutes to run. */
      console.log(`Fetched ${pokeData.name}.`)

      /* Push our pokeData object onto the end of the pokeArray array. This is done each time our loop executes, resulting in an array full of objects - one for each Pokemon that you included in the loop (using the start and end numbers).
      
      Each object will look just like the pokeData object definition above, except the properties will contain actual information. If you want to see how these look, add console.log(pokeData) above this line. */
      pokeArray.push(pokeData)
    })
    .catch((error) => {
      
      /* if axios.get() fails and throws an error, this catch block will catch it and log it in the console. */
      console.log(error)
    })
  }
  
  /* We now need to call another PokeAPI endpoint to get three more pieces of information about each Pokemon:    - Flavor text (e.g. "Spits fire that is hot enough to melt boulders. Known to cause forest fires unintentionally.")  - Generation (e.g. I, II, III...)  - Category (e.g. "Flame Pokemon", "Owl Pokemon")
  
  These must be obtained from the pokemon-species endpoint (https://pokeapi.co/docs/v2#pokemon-species)
  
  We now have all of the Pokemon we'll sent to Notion in pokeArray, so we'll now use a for...of loop to loop through that array,  get the 'species' info for each element from PokeAPI, and add each piece of info to that pokemon's object in pokeArray. */
  for (let pokemon of pokeArray) {
    
    /* Just like we did above, here we use axios.get() to call the PokeAPI endpoint we want. Note that this time we're passing the pokemon.number property from the current element of pokeArray (which is stored in the pokemon variable created in this loop) into the PokeAPI URL. */
    const flavor = await axios.get(`https://pokeapi.co/api/v2/pokemon-species/${pokemon.number}`)
      .then((flavor) => {
        
        /* Create a variable to store the pokemon's flavor text. Depending on the pokemon, PokeAPI will have a differing number of flavor text options. These are all stored in an array called flavor_text_entries, and the English-language flavor text might be at any one of the indexes.
        
        See for yourself: Go to pokeapi.co and enter 'pokemon-species/charmander' in the testing box. Array index 0 (the first one) contains English-language flavor text. 
        
        However, try 'pokemon-species/cramorant' and you'll see that the English flavor text doesn't show up until Array index 7. 
        
        So instead of calling a specific array index, we have to search deeply inside the array's objects to find the one that has a 'language' object, which itself contains a 'name' property with a value of 'en'. 
        
        To accomplish this, we call the find() method on the flavor_text_entries array, which returns the first array element that satisfies a test condition we'll set up though a function. 
        
        That function is name === 'en'. To make sure the value of the nested 'name' property is fed into the function as the 'name' varible, we do what is called nested object destructuring. ({language: { name }}) tells find() that for each array element, go into its language object, then into the name property nested within, and pass name's value as the variable for the function.   
        
        find() returns the full array element that matches the test condition, so we then tack on `.flavor_text` to get the value of its flavor_text property.
        
        Finally, we pass the found value through replace(/\n|\f|\r/g, " ") to replace any newline characters with spaces, resulting in a single line of flavor text. */
        const flavorText = flavor.data.flavor_text_entries.find(({language: { name }}) => name === "en").flavor_text.replace(/\n|\f|\r/g, " ")
        
        
        /* Here we do the exact same thing as was done with the flavorText variable, except for the 'genus' property, which is PokeAPI's term for the category - e.g. "Flame Pokemon" */
        const category = flavor.data.genera.find(({language: { name }}) => name === "en").genus
        
        /* Now we get the pokemon's generation. It is returned in this format: 'generation-i' - but we want it to simply be 'I', so we run the result through split(/-/), which splits the string into an array using the dash character (-) as the divider.
        
        Then we use pop() to "pop" the last element of that array off of the array and return it - this will always be the generation number in Roman numerals, e.g. 'iv'. Finally, we pass that value through toUpperCase() to capitalize it - e.g. 'IV'. */
        const generation = flavor.data.generation.name.split(/-/).pop().toUpperCase()

        /* Now we add our three new pieces of information to the current pokemon's object by creating three new properties within that object, and then assigning them the values from our three variables above.
        
        Note how pokemon['flavor-text'] uses bracket notation; this is required when an object property name has or will have spaces, dashes, or other special characters in it. Dot notation can only be used when property names contain letters, numbers, and underscores. */
        pokemon['flavor-text'] = flavorText
        pokemon.category = category
        pokemon.generation = generation
        
        /* Add a log entry in the console each time this information is fetched from PokeAPI. */
        console.log(`Fetched flavor info for ${pokemon.name}.`)
      })
      .catch((error) => {
        /* Log any errors thrown by axios.get(), just as in the previous loop block. */
        console.log(error)
      })
  }
  
  
  /* Once both loops have finished running, we call the createNotionPage() function which is defined below. It's important to note that we're calling this function within the getPokemon() function. 
  
  Since getPokemon() is an async function, calling createNotionPage() outside of it (in the global context) will cause createNotionPage() to run before getPokemon() can finish construcing its array of objects.
  
  Calling it here forces createNotionPage() to run only after our two loops have completely finished fetching and formatting the data from PokeAPI. */
  createNotionPage();
}

/* Here's where we actually call the getPokemon() function. When you type `node index.js` in the Terminal to run this script, it immediately runs this function, which kicks off everything else.

Note how we've defined additional functions below this; these are totally fine to exist below this line because JavaScript "hoists"function definitions to the top when it actually runs a .js file. Look up "JavaScript Hoisting" to learn more about this. */
getPokemon();


/* Create a "wait" function to comply with Notion API rate-limiting. 

The Notion API only allows ~3 requests per second, so after we create each new page in our Notion database, we'll call this sleep function and have it wait for 300ms. This will ensure that our app doesn't try to send data to Notion too quickly, which would cause our calls to eventually fail. */
const sleep = (milliseconds) => {
  return new Promise(resolve => setTimeout(resolve, milliseconds))
};

/* Create a function for sending our data to the Notion API. As with getPokemon(), this function has to be async because it is using axios.get(), which is an asynchronous method that returns a Promise first. Therefore, we must await it, and to do that it has to be inside an async function. */
async function createNotionPage() {
  
  /* Here's our main loop for the process of sending data to Notion. We already have our array of pokemon objects (pokeArray), so we can use a for...of loop to iterate through it. 
  
  For each element, we'll construct a new object that formats the data in the way   Notion wants. Then we'll create a new page in our Notion database with that data. */
  for (let pokemon of pokeArray) {
    
    /* Here we'll construct the data object that we'll send to Notion in order to create a new page. This object defines the database in which the page will live (the "parent") and sets its icon, cover, and property values. It also adds a few blocks to the page's body, including the flavor text and a link to the pokemon's Bulbapedia page.
    
    I won't verbosely comment every piece of this object definition. Instead, I'll encourage you to study it and also point you to a few reference pages that you'll fine invaluable for working with the Notion API: 
    
    - Property Values: https://developers.notion.com/reference/property-value-object 
    - Block Objects: https://developers.notion.com/reference/block 
    - Create a Page: https://developers.notion.com/reference/post-page 
    
    Note how, for each block, we're setting the relevant property values to the variables in our pokemon object (except for     the database ID, which is set by process.env.NOTION_DATABASE_ID).
    
    It's also useful to note that EVERYTHING in Notion is a block. The 'data' object will end up being a block that is recognized by Notion as a page due to the 'parent' value we're giving it (a database), and due to the fact that we're using the notion.pages.create() method to create it.
    
    However, you can see below that this block has children, which are blocks that will show up as its page content. Note that you can create 'block children' under nearly any block - not just under a page!
    
    See more: https://developers.notion.com/reference/patch-block-children */
    const data = {
      "parent": {
        "type": "database_id",
        "database_id": process.env.NOTION_DATABASE_ID
      },
      "icon": {
        "type": "external",
        "external": {
          "url": pokemon.sprite
        }
      },
      "cover": {
        "type": "external",
        "external": {
          "url": pokemon.artwork
        }
      },
      "properties": {
        "Name": {
          "title": [
            {
              "text": {
                "content": pokemon.name
              }
            }
          ]
        },
        "Category": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": pokemon.category
              }
            }
          ]
        },
        "No": {
          "number": pokemon.number
        },
        "Type": {
          "multi_select": pokemon.types
        },
        "Generation": {
          "select": {
            "name": pokemon.generation
          }
        },
        "Sprite": {
          "files": [
            {
              "type": "external",
              "name": "Pokemon Sprite",
              "external": {
                "url": pokemon.sprite
              }
            }
          ]
        },
        "Height": { "number": pokemon.height },
        "Weight": { "number": pokemon.weight },
        "HP": { "number": pokemon.hp },
        "Attack": { "number": pokemon.attack },
        "Defense": { "number": pokemon.defense },
        "Sp. Attack": { "number": pokemon['special-attack'] },
        "Sp. Defense": { "number": pokemon['special-defense'] },
        "Speed": { "number": pokemon.speed }
      },
      "children": [
        {
          "object": "block",
          "type": "quote",
          "quote": {
            "rich_text": [
              {
                "type": "text",
                "text": {
                  "content": pokemon['flavor-text']
                }
              }
            ]
          }
        },
        {
          "object": "block",
          "type": "paragraph",
          "paragraph": {
            "rich_text": [
              {
                "type": "text",
                "text": {
                  "content": ""
                }
              }
            ]
          }
        },
        {
          "object": "block",
          "type": "paragraph",
          "paragraph": {
            "rich_text": [
              {
                "type": "text",
                "text": {
                  "content": "View This Pokémon's Entry on Bulbapedia:"
                }
              }
            ]
          }
        },
        {
          "object": "block",
          "type": "bookmark",
          "bookmark": {
            "url": pokemon.bulbURL
          }
        }
      ]
    }
    
    /*  Here we call our sleep() function, passing it a value of 300 so that the loop "sleeps" for 300ms before going onto the next cycle. This ensures that we respect the Notion API's rate limit of ~3 requests per second. */
    await sleep(300)
    
    /* Finally, we actually create the new page in our Notion database. First, we add a log item to the console for our own benefit. 
    
    Then we call the notion.pages.create() function, which creates a new page in our database. We pass it our data object (defined above), which contains all of the necessary information.
    
    Finally, we store the Notion API's response in the response variable, and log it. */
    console.log(`Sending ${pokemon.name} to Notion`)
    const response = await notion.pages.create( data )
    console.log(response)
  }
  
  /* When the entire process is done, this will simply print "Operation Complete" in the console. */
  console.log(`Operation complete.`)
}
Code language: JavaScript (javascript)

As I mentioned above, I only learned how to code in JavaScript this year, so my skills are not well-honed.

Fortunately, that doesn’t matter much. These days, computers are so powerful that simple applications can be built many ways. Even if the code isn’t perfectly-optimized, it’s “good enough” so long as it gets the job done and handles errors well.

Still, there are often better ways to do things. To show you an example, below I’m sharing my full-time developer Eli’s take on the getPokemon() function.

He readily admits that his code is less readable than mine, but it does result in a 40% reduction in code length. In professional setting, my code above would probably get refactored to look more like his.

async function getPokemon() {
	
	const replacer = (str) => {
		const n = {
			"Mr M": "Mr. M",
			"Mime Jr": "Mime Jr.",
			"Mr R": "Mr. R",
			"mo O": "mo-o",
			"Porygon Z": "Porygon-Z",
			"Type Null": "Type: Null",
			"Ho Oh": "Ho-Oh",
			"Nidoran F": "Nidoran♀",
			"Nidoran M": "Nidoran♂",
			"Flabebe": "Flabébé",
		}
		let pn = Object.keys(n).find((o) => str.includes(o))
		return pn ? str.replace(pn, n[str]) : str
	}
	
	let urls = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=50`)
		.then((r) => r.json())
		.then((d) => d.results.map(u => u.url))
	
	let base = await Promise.all(urls.map(async (url) => {
		let d = await fetch(url).then((r) => r.json())
		let name = replacer(d.name.split(/-/).map((name) => {
			return name[0].toUpperCase() + name.substring(1)
		})[0])
		
		return {
			name: name,
			number: d.id,
			types: d.types.map((t) => t.type.name),
			height: d.height,
			weight: d.weight,
			hp: d.stats[0].base_stat,
			attack: d.stats[1].base_stat,
			defense: d.stats[2].base_stat,
			specialAttack: d.stats[3].base_stat,
			specialDefense: d.stats[4].base_stat,
			speed: d.stats[5].base_stat,
			sprite: d.sprites.front_default,
			artwork: d.sprites.other['official-artwork'].front_default,
			bulbURL: `https://bulbapedia.bulbagarden.net/wiki/${name.replace(' ', '_')}_(Pokémon)`,
		}
	}))
	
	let flav = await Promise.all(base.map(async (p) => {
		let d = await fetch(`https://pokeapi.co/api/v2/pokemon-species/${p.number}`).then((r) => r.json())
		
		return {
			flavorText: d.flavor_text_entries.find(({language: {name}}) => name === "en").
            flavor_text.replace(/\n|\f|\r/g, " "),
			category: d.genera.find(({language: {name}}) => name === "en").genus,
			generation: d.generation.name.split(/-/).pop().toUpperCase()
		}
	}))
	
	return base.map((b, i) => ({...b, ...flav[i]}))
}
​
getPokemon().then((r) => {
	createNotionPage(r)
})
Code language: JavaScript (javascript)

In 2024, I released an JavaScript library called notion-helper that makes working with the Notion API much easier.

Below you’ll find a version of the Pokédex script above that uses notion-helper, along with a more modern HTTP client called ky. As you can see, it’s a much smaller script!

If you’re new to code, and if you want to thoroughly understand the Notion API, I’d still recommend going through the whole project in this post and writing all the API code from scratch. After that, though, you might find that notion-helper comes in handy when building future API requests.

import ky from "ky";
import { createNotion, createPage } from "notion-helper";
import { Client } from "@notionhq/client";

const notion = new Client({ auth: process.env.NOTION_KEY });
const dbId = "13342df2c64081e5a75fe9a119e75ecc";

const pokedex = await Promise.all(
    Array.from({ length: 20 }, async (_, i) => {
        const poke = await ky
            .get(`https://pokeapi.co/api/v2/pokemon/${i + 1}`).json();
        const species = await ky
            .get(`https://pokeapi.co/api/v2/pokemon-species/${i + 1}`).json();
        const name = species.names.find(
            ({ language: { name } }) => name === "en"
        ).name;
        const sprite = !poke.sprites.front_default
            ? poke.sprites.other["official-artwork"].front_default
            : poke.sprites.front_default;

        return createPage({
            client: notion,
            data: createNotion({ allowBlankParagraphs: true })
                .parentDb(dbId)
                .icon(sprite)
                .cover(poke.sprites.other['official-artwork'].front_default)
                .title("Name", name)
                .richText(
                    "Category",
                    species.genera.find(
                        ({ language: { name } }) => name === "en"
                    ).genus
                )
                .number("No", poke.id)
                .multiSelect("Type", poke.types.map((type) => type.type.name))
                .select(
                    "Generation",
                    species.generation.name.split(/-/).pop().toUpperCase()
                )
                .files("Sprite", sprite)
                .number("Height", poke.height)
                .number("Weight", poke.weight)
                .number("HP", poke.stats[0].base_stat)
                .number("Attack", poke.stats[1].base_stat)
                .number("Defense", poke.stats[2].base_stat)
                .number("Sp. Attack", poke.stats[3].base_stat)
                .number("Sp. Defense", poke.stats[4].base_stat)
                .number("Speed", poke.stats[5].base_stat)
                .quote(species.flavor_text_entries.find(({language: { name }}) => name === "en").flavor_text.replace(/\n|\f|\r/g, " "))
                .paragraph("")
                .paragraph("View This Pokémon's Entry on Bulbapedia:")
                .bookmark(
                    `https://bulbapedia.bulbagarden.net/wiki/${name.replace(
                        " ",
                        "_"
                    )}_(Pokémon)`
                )
                .build()
                .content
        });
    })
);
Code language: JavaScript (javascript)

You can also build and run this project locally on your own computer. Likewise, you could do things like the pros, pushing your code to Github and then deploying it to a company that can host Node.js apps such as Vercel.

The reason I’ve chosen to build this project on Glitch is because it gives you a complete starting point for free. We can code directly in the Glitch editor and then run our code directly in Glitch’s terminal.

If you’d rather build this project locally, here are the prep steps you’ll need to take:

1. Get a code editor – I recommend VS Code, as it has a built-in terminal for running your code along with many extensions and a huge community.
2. Install Node.js and npm. The Node.js LTS installer should install both. Refer to this guide to see other ways to install (included the recommended-yet-harder nvm method), and to see how you can check that node and npm are indeed installed on your machine.
3. Follow this guide to set up VS Code for a Node.js project and to move into the correct directory where you want to build your app.
4. Once you have your project set up with a package.json file, type npm install axios in the terminal and hit Enter to add the Axios package to your project. It should show up in the package.json file under dependencies.
5. Likewise, type npm install @notionhq/client in the terminal and hit Enter to install the Notion SDK package.

Just like on Glitch, you’ll need to create a .env file in your project and add your authentication details to it. However, Glitch automatically takes care of a few things you’ll have to do manually here.

First, type npm install dotenv and hit Enter in the terminal to install the dotenv package and add it to your package.json. (Glitch includes this by default.)

In your project’s root directory (the same top-level folder where package.json is contained), create a filed called .env (no other file extension).

Add your environment variables to this file and hit Save. Replace these default values with your Notion integration key and your target database’s ID. Refer to the Create a Notion Integration section for more detail on this.

NOTION_KEY = blargablargblarg
NOTION_DATABASE_ID = blargblarg
Code language: JavaScript (javascript)

At the top of your index.js file, you’ll also need to include:

require('dotenv').config()
Code language: JavaScript (javascript)

This will allow your app to access the variables defined in your .env file. You can test this by adding these lines to your index.js file, then running node index.js in the terminal:

console.log(process.env.NOTION_KEY)
console.log(process.env.NOTION_DATABASE_ID)
Code language: JavaScript (javascript)

If you plan on pushing your code to Github or otherwise using git for version control, you’ll also want to create a .gitignore file in your project’s root directory. Then, add .env to that file and commit your .gitignore to your repo (see this more comprehensive guide for more detail):

.env
Code language: JavaScript (javascript)

From there, you can follow the rest of the instructions in this tutorial.

If you’d like to learn more about .env files and running things locally, see this guide: How to Use Environment Variables in Node

Node.js is a backend runtime environment that allows JavaScript to be executed outside of the browser.

Originally, JavaScript was designed to be a programming language that could only run in a web browser. This was initially done for security reasons back when JavaScript was first being built in the mid-1990’s.

Over time, people started using JavaScript for more and more purposes. What was once meant to be a simple scripting language started getting used to build complex web applications.

In 2009, Node.js was released in order to allow developers to write the JavaScript syntax they were familiar with in other contexts. Node allows JS code to do all sorts of back-end tasks, like processing user data, reading and writing to file systems, and more.

If you want to learn more about Node.js, watch this video:

A .env file is a special file that contains environmental variables. These are often variables that hold sensitive information, such as authentication tokes for API access.

.env files are never pushed to version-control systems like git, meaning that programmers and teams can use services like Github and even share open-source code without exposing sensitive information.

If you want to learn more, check out this video:

As of this writing (Februrary 2023), both of the npm packages we’ll use in this project are in a working state.

However, I actually went through the experience of dealing with a broken npm package while making this tutorial. After I filmed the video version in November 2022, Axios had a buggy update that broke its ability to make API calls.

To make my script work, I had to manually roll Axios back to the 1.1.3 version.

Today, Axios’ current 1.3.1 version is working – so you (hopefully) shouldn’t have any troubles with it as you go through this tutorial.

That said, if you find that Axios – or any package – isn’t working in the future, here’s what to do.

First, check the package’s Github Issues page to see if others are posting about a potential bug. For example, here’s the Issue I ran into with Axios (you can even see a comment from me in this thread). Checking for Issues on Github can help you confirm that there’s a problem with the package itself, rather than your code.

Second, simply roll back to an earlier version of the package and see if that works. Axios’ 1.2 version broke my script, but I was able to roll back to 1.1.3 to get it working again.

In Glitch, this is incredibly easy – just go into package.json and change the version number of the package. Refresh the page, and Glitch will take care of the downgrade in the background.

Note: If you want to “lock in” a specific version of the package, take care to remove the caret ^ symbol – read up on SemVer if you’re curious about that. E.g. 1.1.3 instead of ^1.1.3.

Elsewhere (such as your own machine with Node.js installed), run the npm install command with the version you want specified, like so:

npm install [email protected]
Code language: Bash (bash)

Even if the package is already installed with a later version, this command will replace it with the older version you specify.

More detail on how to do this can be found at this post:

How to downgrade an installed npm package – Nathan Sebhastian

Learn how you can downgrade an npm package to rollback breaking changes

sebhastian.com

This is the entire response returned by PokeAPI for this API call. Find the data object within it to see how we’re accessing the pokemon’s name (line 238).

Note that, by default, console.log() won’t fully show the details of objects that are nested many layers deep. For that reason, most of the information in the data object is simply labeled [Object].

However, when you access specific properties in your code, you’ll get the actual values. For example, poke.data.species.name has a value of bulbasaur, which we were able to see in the console in the Replit embed above.

{
  status: 200,
  statusText: 'OK',
  headers: AxiosHeaders {
    date: 'Fri, 09 Dec 2022 20:29:25 GMT',
    'content-type': 'application/json; charset=utf-8',
    'transfer-encoding': 'chunked',
    connection: 'close',
    'access-control-allow-origin': '*',
    'cache-control': 'public, max-age=86400, s-maxage=86400',
    etag: 'W/"359f3-JlmmuiyGZkKyOFlSvLzln1IpB6Q"',
    'function-execution-id': 'tkmw3o8u9p36',
    'strict-transport-security': 'max-age=31556926',
    'x-cloud-trace-context': '3dba91851bd1a57c6ea5dade1ac7e883',
    'x-country-code': 'US',
    'x-orig-accept-language': 'en-US',
    'x-powered-by': 'Express',
    'x-served-by': 'cache-iad-kiad7000067-IAD',
    'x-cache': 'HIT',
    'x-cache-hits': '1',
    'x-timer': 'S1669043889.601956,VS0,VE1',
    vary: 'Accept-Encoding,cookie,need-authorization, x-fh-requested-host, accept-encoding',
    'alt-svc': 'h3=":443"; ma=86400, h3-29=":443"; ma=86400',
    'cf-cache-status': 'HIT',
    age: '51296',
    'server-timing': 'cf-q-config;dur=6.9999987317715e-06',
    'report-to': '{"endpoints":[{"url":"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=4KTK4BOb7zSytazr61FEYksT%2BVDQfvoEhzU6Ph%2FYbVr%2Bc9ZgsACueHvhFQy5%2BsijYeXyqKyD3Vo7sBe%2FieNvBWwCdvO%2B55koSkx9YXvyuZQXrpitHk2UCZt3rUoa"}],"group":"cf-nel","max_age":604800}',
    nel: '{"success_fraction":0,"report_to":"cf-nel","max_age":604800}',
    server: 'cloudflare',
    'cf-ray': '77707e289bca208d-IAD',
    [Symbol(defaults)]: null
  },
  config: {
    transitional: {
      silentJSONParsing: true,
      forcedJSONParsing: true,
      clarifyTimeoutError: false
    },
    adapter: [Function: httpAdapter],
    transformRequest: [ [Function: transformRequest] ],
    transformResponse: [ [Function: transformResponse] ],
    timeout: 0,
    xsrfCookieName: 'XSRF-TOKEN',
    xsrfHeaderName: 'X-XSRF-TOKEN',
    maxContentLength: -1,
    maxBodyLength: -1,
    env: { FormData: [Function], Blob: null },
    validateStatus: [Function: validateStatus],
    headers: AxiosHeaders {
      'User-Agent': 'axios/1.1.3',
      'Accept-Encoding': 'gzip, deflate, br',
      [Symbol(defaults)]: [Object]
    },
    method: 'get',
    url: 'https://pokeapi.co/api/v2/pokemon/1',
    data: undefined
  },
  request: <ref *1> ClientRequest {
    _events: [Object: null prototype] {
      abort: [Function (anonymous)],
      aborted: [Function (anonymous)],
      connect: [Function (anonymous)],
      error: [Function (anonymous)],
      socket: [Function (anonymous)],
      timeout: [Function (anonymous)],
      prefinish: [Function: requestOnPrefinish]
    },
    _eventsCount: 7,
    _maxListeners: undefined,
    outputData: [],
    outputSize: 0,
    writable: true,
    destroyed: true,
    _last: true,
    chunkedEncoding: false,
    shouldKeepAlive: false,
    _defaultKeepAlive: true,
    useChunkedEncodingByDefault: false,
    sendDate: false,
    _removedConnection: false,
    _removedContLen: false,
    _removedTE: false,
    _contentLength: 0,
    _hasBody: true,
    _trailer: '',
    finished: true,
    _headerSent: true,
    socket: TLSSocket {
      _tlsOptions: [Object],
      _secureEstablished: true,
      _securePending: false,
      _newSessionPending: false,
      _controlReleased: true,
      secureConnecting: false,
      _SNICallback: null,
      servername: 'pokeapi.co',
      alpnProtocol: false,
      authorized: true,
      authorizationError: null,
      encrypted: true,
      _events: [Object: null prototype],
      _eventsCount: 9,
      connecting: false,
      _hadError: false,
      _parent: null,
      _host: 'pokeapi.co',
      _readableState: [ReadableState],
      _maxListeners: undefined,
      _writableState: [WritableState],
      allowHalfOpen: false,
      _sockname: null,
      _pendingData: null,
      _pendingEncoding: '',
      server: undefined,
      _server: null,
      ssl: null,
      _requestCert: true,
      _rejectUnauthorized: true,
      parser: null,
      _httpMessage: [Circular *1],
      [Symbol(res)]: null,
      [Symbol(verified)]: true,
      [Symbol(pendingSession)]: null,
      [Symbol(async_id_symbol)]: 3,
      [Symbol(kHandle)]: null,
      [Symbol(kSetNoDelay)]: false,
      [Symbol(lastWriteQueueSize)]: 0,
      [Symbol(timeout)]: null,
      [Symbol(kBuffer)]: null,
      [Symbol(kBufferCb)]: null,
      [Symbol(kBufferGen)]: null,
      [Symbol(kCapture)]: false,
      [Symbol(kBytesRead)]: 6334,
      [Symbol(kBytesWritten)]: 175,
      [Symbol(connect-options)]: [Object],
      [Symbol(RequestTimeout)]: undefined
    },
    _header: 'GET /api/v2/pokemon/1 HTTP/1.1\r\n' +
      'Accept: application/json, text/plain, */*\r\n' +
      'User-Agent: axios/1.1.3\r\n' +
      'Accept-Encoding: gzip, deflate, br\r\n' +
      'Host: pokeapi.co\r\n' +
      'Connection: close\r\n' +
      '\r\n',
    _keepAliveTimeout: 0,
    _onPendingData: [Function: noopPendingOutput],
    agent: Agent {
      _events: [Object: null prototype],
      _eventsCount: 2,
      _maxListeners: undefined,
      defaultPort: 443,
      protocol: 'https:',
      options: [Object],
      requests: {},
      sockets: {},
      freeSockets: {},
      keepAliveMsecs: 1000,
      keepAlive: false,
      maxSockets: Infinity,
      maxFreeSockets: 256,
      scheduling: 'lifo',
      maxTotalSockets: Infinity,
      totalSocketCount: 0,
      maxCachedSessions: 100,
      _sessionCache: [Object],
      [Symbol(kCapture)]: false
    },
    socketPath: undefined,
    method: 'GET',
    maxHeaderSize: undefined,
    insecureHTTPParser: undefined,
    path: '/api/v2/pokemon/1',
    _ended: true,
    res: IncomingMessage {
      _readableState: [ReadableState],
      _events: [Object: null prototype],
      _eventsCount: 5,
      _maxListeners: undefined,
      socket: [TLSSocket],
      httpVersionMajor: 1,
      httpVersionMinor: 1,
      httpVersion: '1.1',
      complete: true,
      headers: [Object],
      rawHeaders: [Array],
      trailers: {},
      rawTrailers: [],
      aborted: false,
      upgrade: false,
      url: '',
      method: null,
      statusCode: 200,
      statusMessage: 'OK',
      client: [TLSSocket],
      _consuming: true,
      _dumped: false,
      req: [Circular *1],
      responseUrl: 'https://pokeapi.co/api/v2/pokemon/1',
      redirects: [],
      [Symbol(kCapture)]: false,
      [Symbol(RequestTimeout)]: undefined
    },
    aborted: false,
    timeoutCb: null,
    upgradeOrConnect: false,
    parser: null,
    maxHeadersCount: null,
    reusedSocket: false,
    host: 'pokeapi.co',
    protocol: 'https:',
    _redirectable: Writable {
      _writableState: [WritableState],
      _events: [Object: null prototype],
      _eventsCount: 3,
      _maxListeners: undefined,
      _options: [Object],
      _ended: true,
      _ending: true,
      _redirectCount: 0,
      _redirects: [],
      _requestBodyLength: 0,
      _requestBodyBuffers: [],
      _onNativeResponse: [Function (anonymous)],
      _currentRequest: [Circular *1],
      _currentUrl: 'https://pokeapi.co/api/v2/pokemon/1',
      [Symbol(kCapture)]: false
    },
    [Symbol(kCapture)]: false,
    [Symbol(kNeedDrain)]: false,
    [Symbol(corked)]: 0,
    [Symbol(kOutHeaders)]: [Object: null prototype] {
      accept: [Array],
      'user-agent': [Array],
      'accept-encoding': [Array],
      host: [Array]
    }
  },
  data: {
    abilities: [ [Object], [Object] ],
    base_experience: 64,
    forms: [ [Object] ],
    game_indices: [
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object]
    ],
    height: 7,
    held_items: [],
    id: 1,
    is_default: true,
    location_area_encounters: 'https://pokeapi.co/api/v2/pokemon/1/encounters',
    moves: [
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object]
    ],
    name: 'bulbasaur',
    order: 1,
    past_types: [],
    species: {
      name: 'bulbasaur',
      url: 'https://pokeapi.co/api/v2/pokemon-species/1/'
    },
    sprites: {
      back_default: 'https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/back/1.png',
      back_female: null,
      back_shiny: 'https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/back/shiny/1.png',
      back_shiny_female: null,
      front_default: 'https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/1.png',
      front_female: null,
      front_shiny: 'https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/shiny/1.png',
      front_shiny_female: null,
      other: [Object],
      versions: [Object]
    },
    stats: [ [Object], [Object], [Object], [Object], [Object], [Object] ],
    types: [ [Object], [Object] ],
    weight: 69
  }
}
Code language: JavaScript (javascript)

Pipedream is a code-light platform that I’ll be featuring in upcoming tutorials; it’s generally a much easier tool for working with the Notion API and creating automations compared to what we’re doing here. I’ve used it personally to mirror Notion databases, send YouTube stats to Notion, create a speech-to-text automation, and more.

I’m not using it for this tutorial because I want you to be fully aware of what’s happening while you learn the Notion API, and because you may want to go off and build apps on your own tech stack! So this tutorial is sticking to more general purpose tools – but I did want to base it off of Axios so you’ll be fully prepped when you deal with it on Pipedream.

Axios is a “promise-based” library, which means that when we use the axios.get() method, we get a Promise.

In JavaScript, a Promise is essentially an IOU. It’s almost as if JavaScript is handing you a piece of paper that says:

“I promise to give you the full results of this API call if it is successful. And if it fails, I’ll give you details about the error.

The actual response, be it the successfully-retrieved data from the API or an error message, comes later on once the Promise resolves.

In general, this is quite useful because JavaScript is a single-threaded language, which means that it generally can only do one thing at a time.

This can become a problem with API calls, because they can often take a (relatively) long time to execute. In a program where lots of things are happening, an API call can block additional code steps that would otherwise execute extremely fast.

Promises allow that later code to execute before something like an API call finishes, since the Promise gets returned almost immediately. In complex applications, this means later code steps can do their thing, and then once the Promise resolves, you can take action on the actual response from the API.

As I mentioned above, I’m choosing Axios for this project specifically because Pipedream uses it heavily and I’ll be doing lots of Pipedream/Notion API tutorials in the future.

However, what we’re doing here doesn’t really need Promises or async/await. Our script is going to get all the information about all the Pokemon before doing anything else, so we would be fine to go with a totally synchronous option here if we wanted.

Still, asynchronous JavaScript can be very useful in other cases. If you want to learn more about it, here are some resources.

First, I highly recommend watching this talk on the Javascript event loop if you want to understand how JavaScript can be “asynchronous” despite being single-threaded:

Next, I’d recommend watching my friend Daniel Shiffman’s series on Promises and async/await:

JSInfo also has some great articles on these topics:

• Promises
• Async/await

At this point, your code should look exactly like this:

const axios = require('axios')
const { Client } = require('@notionhq/client')


const notion = new Client({auth: process.env.NOTION_KEY})


const pokeArray = []

async function getPokemon() {
  
  const start = 1
  const end = 10
  for (let i = start; i <= end; i++) {
    
    const poke = await axios.get(`https://pokeapi.co/api/v2/pokemon/${i}`)
      .then((poke) => {
        
        console.log(poke.data.species.name)
        
      })
      .catch((error) => {
        console.log(error)
      })
    
  }
  
}

getPokemon()
Code language: JavaScript (javascript)

At this stage, your code should look just like this:

const axios = require('axios')
const { Client } = require('@notionhq/client')


const notion = new Client({auth: process.env.NOTION_KEY})


const pokeArray = []

async function getPokemon() {
  
  const start = 1
  const end = 1
  for (let i = start; i <= end; i++) {
    
    const poke = await axios.get(`https://pokeapi.co/api/v2/pokemon/${i}`)
      .then((poke) => {
        
        const pokeData = {
          "name": poke.data.species.name,
          "number": poke.data.id,
          "height": poke.data.height,
          "weight": poke.data.weight,
          "hp": poke.data.stats[0].base_stat,
          "attack": poke.data.stats[1].base_stat,
          "defense": poke.data.stats[2].base_stat,
          "special-attack": poke.data.stats[3].base_stat,
          "special-defense": poke.data.stats[4].base_stat,
          "speed": poke.data.stats[5].base_stat
        }
        
        console.log(`Fetched ${pokeData.name}.`)
        console.table(pokeData)
        
      })
      .catch((error) => {
        console.log(error)
      })
    
  }
  
}

getPokemon()
Code language: JavaScript (javascript)

In the code above, you can see that we’re using a for...of loop to iterate over our array:

for (let pokemon of pokeArray) {

}
Code language: JavaScript (javascript)

This is a type of for loop that can iterate over the values of an array or an object (for... in loops can iterate over the keys).

You can see the differences between for...of and for...in here:

For-In vs For-Of | Kevin Chisholm – Blog

blog.kevinchisholm.com

In most cases, you want to access the actual values of an object or array, so a for...of loop is cleaner.

Note that you could also write a normal for loop, using the array’s length to set the end parameter:

for (let i = 0; i < pokeArray.length; i++) {

}
Code language: JavaScript (javascript)

Since we’re working on an array, these approaches are functionally identical.

Note that you can use the dropdown menus to see other requests. The default example uses the official Notion SDK for JavaScript, which we’re using in this project as well. It provides lots of handy methods for making API requests without writing as much code.

However, you can see several other examples. If you change the dropdown from Notion SDK to Axios, for example, you’ll see this code:

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.notion.com/v1/pages',
  headers: {
    accept: 'application/json',
    'Notion-Version': '2022-06-28',
    'content-type': 'application/json'
  }
};

axios
  .request(options)
  .then(function (response) {
    console.log(response.data);
  })
  .catch(function (error) {
    console.error(error);
  });
Code language: JavaScript (javascript)

My only issue with this example code is that it actually doesn’t give you all of the information you need to make a request using Axios. Perhaps they’ll fix this in the future (you may see different code if you’re reading this well after I publish it), but for now, it’s incomplete.

Here’s the full code you’d need to use to create a page using Axios:

const axios = require('axios')

const options = {
  method: 'POST',
  url: 'https://api.notion.com/v1/pages/',
  headers: {
    accept: 'application/json',
    'Notion-Version': '2022-06-28',
    'content-type': 'application/json',
    Authorization: `Bearer ${process.env.NOTION_KEY}`
  },
  data: {
    parent: {
      "type": "database_id",
      "database_id": process.env.NOTION_DATABASE_ID
    },
    properties: {
      "Name": {
        "title": [
          {
            "text": {
              "content": "Test Page"
            }
          }
        ]
      }
    }
  }
};

axios
  .request(options)
  .then(function (response) {
    console.log(response.data);
  })
  .catch(function (error) {
    console.error(error);
  });
Code language: JavaScript (javascript)

The code is quite similar, but you can see that I’ve included two new pieces of information:

1. An Authorization property in the headers object, containing my integration’s secret key
2. A data object that contains both the parent and the properties.

Both of these are required, yet they aren’t shown in the Axios example.

This is a harsh truth I’ve learned as I’ve gone through my journey of learning APIs; you’re often expected to know a lot of fundamentals, and API documentation often doesn’t hold your hand. This is likely because developers are trying to write mountains of documentation very quickly, and they’re also experienced enough to know the missing pieces by heart.

Unfortunately, us noobs are often left scratching our heads as a result!

At this stage, your code should look just like this:

const axios = require('axios')
const { Client } = require('@notionhq/client')

const notion = new Client({auth: process.env.NOTION_KEY})


const pokeArray = []

async function getPokemon() {
  
  const start = 1
  const end = 1
  for (let i = start; i <= end; i++) {
    
    const poke = await axios.get(`https://pokeapi.co/api/v2/pokemon/${i}`)
      .then((poke) => {
        
        const pokeData = {
          "name": poke.data.species.name,
          "number": poke.data.id,
          "height": poke.data.height,
          "weight": poke.data.weight,
          "hp": poke.data.stats[0].base_stat,
          "attack": poke.data.stats[1].base_stat,
          "defense": poke.data.stats[2].base_stat,
          "special-attack": poke.data.stats[3].base_stat,
          "special-defense": poke.data.stats[4].base_stat,
          "speed": poke.data.stats[5].base_stat
        }
        
        console.log(`Fetched ${pokeData.name}.`)
        console.table(pokeData)
        
        pokeArray.push(pokeData)
        
      })
      .catch((error) => {
        console.log(error)
      })
    
  }
  
  createNotionPage()
  
}

getPokemon()

async function createNotionPage() {
  
  for (let pokemon of pokeArray) {
    
    const data = {
      "parent": {
        "type": "database_id",
        "database_id": process.env.NOTION_DATABASE_ID
      }, 
      "properties": {
        "Name": {
          "title": [
            {
              "text": {
                "content": pokemon.name
              }
            }
          ]
        },
        "No": {
          "number": pokemon.number
        },
        "Height": { "number": pokemon.height },
        "Weight": { "number": pokemon.weight },
        "HP": { "number": pokemon.hp },
        "Attack": { "number": pokemon.attack },
        "Defense": { "number": pokemon.defense },
        "Sp. Attack": { "number": pokemon['special-attack'] },
        "Sp. Defense": { "number": pokemon['special-defense'] },
        "Speed": { "number": pokemon.speed }
      }
    }
    
    console.log(`Sending ${pokemon.name} to Notion`)
    const response = await notion.pages.create( data )
    console.log(response)
    
  }
  
  console.log(`Operation complete.`)
  
}
Code language: JavaScript (javascript)

You don’t really need to understand the nuts and bolts of the sleep() function to use it; you can basically just copy and paste. However, if you’re curious about how and why it works, here’s a brief overview.

The built-in setTimeout() function will set a timer and execute a function after the timer is up. Here’s the reference for it:

setTimeout() – Web APIs | MDN

The global setTimeout() method sets a timer which executes a function or specified piece of code once the timer expires.

developer.mozilla.org

However, setTimeout() will not delay the execution of the next line of code.

We can get around this issue by creating a Promise within our sleep() function, which is only fulfilled after the setTimeout() call inside it has finished running.

Then, by calling the function with the await keyword (e.g. await sleep(300)), we effectively cause our script to pause for 300 milliseconds before moving on.

The MDN documentation on Promises explains why this works:

Promise – JavaScript | MDN

The Promise object represents the eventual completion (or failure) of an asynchronous operation and its resulting value.

developer.mozilla.org

You can also get more detail on this sleep() function itself here:

JavaScript Sleep: How to Pause Code Execution

JavaScript does not have an inbuilt sleep function but thanks to the introduction of promises and async/await, we can implement such sleep in JavaScript.

appdividend.com

At this stage, your code should look just like this:

const axios = require('axios')
const { Client } = require('@notionhq/client')

const notion = new Client({auth: process.env.NOTION_KEY})


const pokeArray = []

async function getPokemon() {
  
  const start = 1
  const end = 10
  for (let i = start; i <= end; i++) {
    
    const poke = await axios.get(`https://pokeapi.co/api/v2/pokemon/${i}`)
      .then((poke) => {
        
        const pokeData = {
          "name": poke.data.species.name,
          "number": poke.data.id,
          "height": poke.data.height,
          "weight": poke.data.weight,
          "hp": poke.data.stats[0].base_stat,
          "attack": poke.data.stats[1].base_stat,
          "defense": poke.data.stats[2].base_stat,
          "special-attack": poke.data.stats[3].base_stat,
          "special-defense": poke.data.stats[4].base_stat,
          "speed": poke.data.stats[5].base_stat
        }
        
        console.log(`Fetched ${pokeData.name}.`)
        console.table(pokeData)
        
        pokeArray.push(pokeData)
        
      })
      .catch((error) => {
        console.log(error)
      })
    
  }
  
  createNotionPage()
  
}

getPokemon()

const sleep = (milliseconds) => {
  return new Promise(resolve => setTimeout(resolve, milliseconds))
};

async function createNotionPage() {
  
  for (let pokemon of pokeArray) {
    
    const data = {
      "parent": {
        "type": "database_id",
        "database_id": process.env.NOTION_DATABASE_ID
      }, 
      "properties": {
        "Name": {
          "title": [
            {
              "text": {
                "content": pokemon.name
              }
            }
          ]
        },
        "No": {
          "number": pokemon.number
        },
        "Height": { "number": pokemon.height },
        "Weight": { "number": pokemon.weight },
        "HP": { "number": pokemon.hp },
        "Attack": { "number": pokemon.attack },
        "Defense": { "number": pokemon.defense },
        "Sp. Attack": { "number": pokemon['special-attack'] },
        "Sp. Defense": { "number": pokemon['special-defense'] },
        "Speed": { "number": pokemon.speed }
      }
    }
    
    await sleep(300)
    
    console.log(`Sending ${pokemon.name} to Notion`)
    const response = await notion.pages.create( data )
    console.log(response)
    
  }
  
  console.log(`Operation complete.`)
  
}
Code language: JavaScript (javascript)