{"id":15284158,"url":"https://github.com/nyoungstudios/notion-py-requests","last_synced_at":"2026-01-05T06:18:40.183Z","repository":{"id":57446898,"uuid":"427502477","full_name":"nyoungstudios/notion-py-requests","owner":"nyoungstudios","description":"Notion Python SDK Client using Requests","archived":false,"fork":false,"pushed_at":"2021-11-17T00:05:48.000Z","size":22,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-04T20:07:49.332Z","etag":null,"topics":["notion","notion-api","python","python-api-wrapper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nyoungstudios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-12T21:37:03.000Z","updated_at":"2024-03-03T04:00:32.000Z","dependencies_parsed_at":"2022-09-05T09:40:58.451Z","dependency_job_id":null,"html_url":"https://github.com/nyoungstudios/notion-py-requests","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyoungstudios%2Fnotion-py-requests","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyoungstudios%2Fnotion-py-requests/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyoungstudios%2Fnotion-py-requests/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyoungstudios%2Fnotion-py-requests/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nyoungstudios","download_url":"https://codeload.github.com/nyoungstudios/notion-py-requests/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245138186,"owners_count":20566883,"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":["notion","notion-api","python","python-api-wrapper"],"created_at":"2024-09-30T14:50:09.598Z","updated_at":"2026-01-05T06:18:40.131Z","avatar_url":"https://github.com/nyoungstudios.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eNotion Python Requests\u003c/h1\u003e\n\n[![tests](https://github.com/nyoungstudios/notion-py-requests/actions/workflows/python_test.yml/badge.svg)](https://github.com/nyoungstudios/notion-py-requests/actions/workflows/python_test.yml)\n[![codecov](https://codecov.io/gh/nyoungstudios/notion-py-requests/branch/main/graph/badge.svg?token=9M2UZ4WJ36)](https://codecov.io/gh/nyoungstudios/notion-py-requests)\n[![Gitpod ready](https://img.shields.io/badge/Gitpod-ready-blue?logo=gitpod)](https://gitpod.io/#https://github.com/nyoungstudios/notion-py-requests)\n[![PyPI version shields.io](https://img.shields.io/pypi/v/notion-requests.svg)](https://pypi.python.org/project/notion-requests/)\n[![PyPI license](https://img.shields.io/pypi/l/notion-requests.svg)](https://pypi.python.org/project/notion-requests/)\n\nThis is a mostly unopinionated Python client for Notion's API using the Python Requests library. This means that the\nstructure of functions and usage of this client library is almost identical to the official\n[Notion JavaScript SDK](https://developers.notion.com/reference/intro). The only opinionated part is that this client\nlibrary automatically handles pagination, so you do not have to.\n\n## Why?\nWhy does this library exist when there are other Python Notion clients available?\n- [`notion-py`](https://github.com/jamalex/notion-py) - This reverse engineers Notion's internal API and was created\n    before Notion officially released their public beta API\n- [`notion-sdk-py`](https://github.com/ramnes/notion-sdk-py) - This uses Notion's official public beta API and\n    uses `httpx` internally to make the requests. And it only supports Python 3.7 or later. And supports sync and async\n    requests.\n\nBut the real reason why this library exists was because I was testing `notion-sdk-py` and was having trouble making a\ndatabase query with filtering. So, I ended up writing this client, and it was not until I wrote the unittests that I\nfigured out the original problem. So, you should probably use `notion-sdk-py` instead, but why delete this perfectly\ngood code that I wrote. You might prefer to use this client library over `notion-sdk-py` if you are already using\n`requests` (and don't want another dependency). Or you need Python 3.6 support. Or you like to have automatic\npagination.\n\n## Install\n\n```shell\npip install notion-requests\n```\n\n## Quickstart\n\n```python\nimport json\nimport os\nfrom notion_requests import Client\n\n# initialize a Notion client\nnotion = Client(os.environ['NOTION_TOKEN'])\n\n# get current user\nresponse = notion.users.me()\nprint(json.dumps(response, indent=2))\n```\n\n```json\n{\n  \"object\": \"user\",\n  \"id\": \"16d84278-ab0e-484c-9bdd-b35da3bd8905\",\n  \"name\": \"pied piper\",\n  \"avatar_url\": null,\n  \"type\": \"bot\",\n  \"bot\": {\n    \"owner\": {\n      \"type\": \"user\",\n      \"user\": {\n        \"object\": \"user\",\n        \"id\": \"5389a034-eb5c-47b5-8a9e-f79c99ef166c\",\n        \"name\": \"christine makenotion\",\n        \"avatar_url\": null,\n        \"type\": \"person\",\n        \"person\": {\n          \"email\": \"christine@makenotion.com\"\n        }\n      }\n    }\n  }\n}\n```\n\n```python\nquery = {\n    'database_id': '897e5a76-ae52-4b48-9fdf-e71f5945d1af',\n    'filter': {\n        'or': [\n            {\n                'property': 'In stock',\n                'checkbox': {\n                    'equals': True\n                }\n            },\n            {\n                'property': 'Cost of next trip',\n                'number': {\n                    'greater_than_or_equal_to': 2\n                }\n            }\n        ]\n    },\n    'sorts': [\n        {\n            'property': 'Last ordered',\n            'direction': 'ascending'\n        }\n    ]\n}\n\n# query a database\n# it returns a generator object since this api endpoint supports pagination\nfor response in notion.databases.query(**query):\n    for result in response['results']:\n        print(json.dumps(result, indent=2))\n```\n\n```json\n{\n  \"object\": \"page\",\n  \"id\": \"2e01e904-febd-43a0-ad02-8eedb903a82c\",\n  \"created_time\": \"2020-03-17T19:10:04.968Z\",\n  \"last_edited_time\": \"2020-03-17T21:49:37.913Z\",\n  \"parent\": {\n    \"type\": \"database_id\",\n    \"database_id\": \"897e5a76-ae52-4b48-9fdf-e71f5945d1af\"\n  },\n  \"archived\": false,\n  \"url\": \"https://www.notion.so/2e01e904febd43a0ad028eedb903a82c\",\n  \"properties\": {\n    \"Recipes\": {\n      \"id\": \"Ai`L\",\n      \"type\": \"relation\",\n      \"relation\": [\n        {\n          \"id\": \"796659b4-a5d9-4c64-a539-06ac5292779e\"\n        },\n        {\n          \"id\": \"79e63318-f85a-4909-aceb-96a724d1021c\"\n        }\n      ]\n    },\n    \"Cost of next trip\": {\n      \"id\": \"R}wl\",\n      \"type\": \"formula\",\n      \"formula\": {\n        \"type\": \"number\",\n        \"number\": 2\n      }\n    },\n    \"Last ordered\": {\n      \"id\": \"UsKi\",\n      \"type\": \"date\",\n      \"date\": {\n        \"start\": \"2020-10-07\",\n        \"end\": null\n      }\n    },\n    \"In stock\": {\n      \"id\": \"{\u003eU;\",\n      \"type\": \"checkbox\",\n      \"checkbox\": false\n    }\n  }\n}\n...\n```\n\n## Error Handling\n```python\nimport requests\n\ntry:\n    # try to retrieve a database that doesn't exist\n    response = notion.databases.retrieve('897e5a76ae524b489fdfe71f5945d1af')\nexcept requests.exceptions.HTTPError as e:\n    # prints json output from failed request\n    print(json.dumps(e.response.json(), indent=2))\n```\n\n```json\n{\n  \"object\": \"error\",\n  \"status\": 404,\n  \"code\": \"object_not_found\",\n  \"message\": \"Could not find database with ID: 897e5a76-ae52-4b48-9fdf-e71f5945d1af.\"\n}\n```\n\n## More Documentation\nThe example data in the above quickstart was taken directly from Notion's API reference and adapted for this client\nlibrary. For more documentation about which functions to use and the inputs of this client library, you can check out\nthe [official Notion JavaScript SDK documentation](https://developers.notion.com/reference/intro).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyoungstudios%2Fnotion-py-requests","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnyoungstudios%2Fnotion-py-requests","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyoungstudios%2Fnotion-py-requests/lists"}