{"id":14483526,"url":"https://github.com/TimRobinson1/notional","last_synced_at":"2025-08-30T04:31:04.387Z","repository":{"id":42264255,"uuid":"270886277","full_name":"TimRobinson1/notional","owner":"TimRobinson1","description":"An unofficial Notion API for interacting with table data in NodeJS","archived":false,"fork":false,"pushed_at":"2023-01-06T08:22:25.000Z","size":413,"stargazers_count":20,"open_issues_count":13,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-06-12T15:08:58.184Z","etag":null,"topics":["api-client","api-wrapper","javascript","nodejs","notion","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimRobinson1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-09T02:41:55.000Z","updated_at":"2024-05-30T20:26:25.000Z","dependencies_parsed_at":"2023-02-05T17:00:58.599Z","dependency_job_id":null,"html_url":"https://github.com/TimRobinson1/notional","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimRobinson1%2Fnotional","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimRobinson1%2Fnotional/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimRobinson1%2Fnotional/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimRobinson1%2Fnotional/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimRobinson1","download_url":"https://codeload.github.com/TimRobinson1/notional/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":217593012,"owners_count":16201561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","api-wrapper","javascript","nodejs","notion","typescript"],"created_at":"2024-09-03T00:01:50.209Z","updated_at":"2024-09-03T00:06:06.147Z","avatar_url":"https://github.com/TimRobinson1.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cimg src=\"https://assets.dryicons.com/uploads/icon/svg/2031/security.svg\" title=\"Notional\" alt=\"Notional\" width=\"100px\"\u003e\n\n# Notional\n\n\u003e An unofficial Notion API for interacting with table data in NodeJS\n\n_Notional: Existing as or based on a suggestion, estimate, or theory_ -- \u003ca href=\"https://dictionary.cambridge.org/dictionary/english/notional\"\u003eCambridge Dictionary\u003c/a\u003e\n\n---\n\n## Basic Usage\nNotional is still very much a work in progress, so please use with a degree of caution.\n\n### Installation\n```\nnpm i notional\n\nyarn add notional\n```\n\n### Getting setup\nTo use `notional`, you'll need both an API key and your user ID. To acquire these, follow these steps:\n- Using a browser (Google Chrome in this example), visit a Notion webpage and make sure you're logged in.\n- Open your developer tools and navigate to the `Application` tab.\n- Under `Storage`, click on `Cookies` and then click on cookies from `https://www.notion.so`.\n- Here you should find a cookie called `token_v2`. This value is your `apiKey`.\n- You should also see `notion_user_id`, which you will need as your `userId`.\n\n### Tables\nLet's say we have a table in Notion to keep track of our video games:\n\n\u003cimg src=\"https://i.ibb.co/JHtRPFQ/Screenshot-2020-06-09-at-2-45-09-am.png\" /\u003e\n\n#### Reading from the table\nNice. Let's connect to that table in our code using `notional`, and read from our table all of the PC games that we have in our collection:\n\n```javascript\nimport notional from 'notional';\n\n// Let's just pretend that this is the URL of our table!\nconst TABLE_URL = 'https://www.notion.so/example/481ff7846d1a4f1c8f30e3a3911d9129';\n\nconst { table } = notional({\n  apiKey: process.env.NOTION_API_KEY,\n  userId: process.env.USER_ID,\n});\n\nasync function readOutMyPCGames () {\n  const videoGamesTable = await table(TABLE_URL);\n  \n  const pcGames = await videoGamesTable\n    .where({ Platform: 'PC' })\n    .get();\n\n  console.log(pcGames);\n}\n```\n\nIf we were to run that `readOutMyPCGames` function, we'd end up with an output like so:\n\n```json\n[\n  {\n    \"Title\": \"Resident Evil 2\",\n    \"Platform\": \"PC\",\n    \"Genres\": [\"action\", \"horror\", \"shooter\"],\n    \"Finished\": true,\n    \"Date purchased\": {\n      \"type\": \"date\",\n      \"start_date\": \"2020-03-19\"\n    }\n  },\n  {\n    \"Title\": \"Fallout 4\",\n    \"Platform\": \"PC\",\n    \"Genres\": [\"action\", \"shooter\"],\n    \"Finished\": false,\n    \"Date purchased\": {\n      \"type\": \"date\",\n      \"start_date\": \"2019-10-22\"\n    }\n  },\n  {\n    \"Title\": \"Skyrim\",\n    \"Platform\": \"PC\",\n    \"Genres\": [\"adventure\"],\n    \"Finished\": false,\n    \"Date purchased\": {\n      \"type\": \"date\",\n      \"start_date\": \"2017-11-09\"\n    }\n  }\n]\n```\n\n#### Updating the table\nI finished _Super Mario Odyssey_ recently, but it looks like the table is out of date and says I haven't finished it! Let's correct that.\n\nWe can set up the `videoGamesTable` variable in the same way as before, and then all we have to do:\n\n```javascript\nawait videoGamesTable\n  .where({ Title: 'Super Mario Odyssey' })\n  .update({ Finished: true });\n```\n\n#### Inserting into the table\nI've just bought the video game _Dark Souls_ this exact second, let's add that to our table!\n\n```javascript\nawait videoGamesTable.insertRows([\n  {\n    \"Title\": \"Dark Souls\",\n    \"Platform\": \"Xbox 360\",\n    \"Genres\": [\"action\", \"adventure\"],\n    \"Finished\": false,\n    \"Date purchased\": (new Date()).toISOString(),\n  }\n])\n```\n\n#### Deleting from the table\nI don't think I'm going to be playing any more _Skyrim_ any time soon. In fact, let's just get rid of it and remove it from our table:\n\n```javascript\nawait videoGamesTable\n  .where({ Title: 'Skyrim' })\n  .delete();\n```\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTimRobinson1%2Fnotional","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTimRobinson1%2Fnotional","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTimRobinson1%2Fnotional/lists"}