diegosouzapw Notion API Integration Skill
Master the Notion API for workspace automation, including databases, pages, blocks, query/filter syntax, and integration patterns. This skill covers the official REST API and Python SDK for building powerful Notion integrations.
When to Use This Skill
USE Notion API when:
- Automating database entries and updates
- Building custom dashboards from Notion data
- Syncing data between Notion and external systems
- Creating pages programmatically from templates
- Querying databases with complex filters
- Building integrations with other productivity tools
- Generating reports from Notion databases
- Implementing workflow automations
DON'T USE Notion API when:
- Need real-time sync (API has rate limits)
- Building chat/messaging features (use Slack API)
- Need file storage solution (use dedicated storage)
- Simple task management only (use Todoist API)
- Need offline-first solution (use Obsidian)
- Require sub-second response times
Prerequisites
Create Integration
1. Go to https://www.notion.so/my-integrations
2. Click "New integration"
3. Name: "My Integration"
4. Select workspace
5. Set capabilities (Read/Write content, etc.)
6. Copy the "Internal Integration Token"
Connect Integration to Pages
1. Open the Notion page/database you want to access
2. Click "..." menu (top right)
3. Click "Connections" > "Connect to" > Your integration
4. Integration can now access this page and children
Environment Setup
# Set environment variable
export NOTION_API_KEY="secret_xxxxxxxxxxxxxxxxxxxxx"
# Verify connection
curl -s "https://api.notion.com/v1/users/me" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2022-06-28" | jq
Python SDK Installation
# Install official Python client
pip install notion-client
# Or with uv
uv pip install notion-client
# Additional dependencies
pip install python-dotenv requests
Verify Setup
from notion_client import Client
import os
notion = Client(auth=os.environ["NOTION_API_KEY"])
# Test connection
me = notion.users.me()
print(f"Connected as: {me['name']}")
# List accessible databases
databases = notion.search(filter={"property": "object", "value": "database"})
print(f"Found {len(databases['results'])} databases")
Core Capabilities
1. Database Operations
List and Search Databases:
# Search for databases
curl -s -X POST "https://api.notion.com/v1/search" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2022-06-28" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"property": "object",
"value": "database"
}
}' | jq '.results[] | {id: .id, title: .title[0].plain_text}'
# Get database schema
curl -s "https://api.notion.com/v1/databases/DATABASE_ID" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2022-06-28" | jq '.properties'
Python - Database Operations:
from notion_client import Client
import os
notion = Client(auth=os.environ["NOTION_API_KEY"])
# Search for databases
results = notion.search(
filter={"property": "object", "value": "database"}
)
for db in results["results"]:
title = db["title"][0]["plain_text"] if db["title"] else "Untitled"
print(f"Database: {title} (ID: {db['id']})")
# Get database details
database = notion.databases.retrieve(database_id="your-database-id")
print(f"Properties: {list(database['properties'].keys())}")
# Create database
new_db = notion.databases.create(
parent={"type": "page_id", "page_id": "parent-page-id"},
title=[{"type": "text", "text": {"content": "Tasks Database"}}],
properties={
"Name": {"title": {}},
"Status": {
"select": {
"options": [
{"name": "To Do", "color": "gray"},
{"name": "In Progress", "color": "blue"},
{"name": "Done", "color": "green"}
]
}
},
"Priority": {
"select": {
"options": [
{"name": "High", "color": "red"},
{"name": "Medium", "color": "yellow"},
{"name": "Low", "color": "gray"}
]
}
},
"Due Date": {"date": {}},
"Assignee": {"people": {}},
"Tags": {"multi_select": {"options": []}},
"Completed": {"checkbox": {}},
"Notes": {"rich_text": {}}
}
)
print(f"Created database: {new_db['id']}")
# Update database
notion.databases.update(
database_id="your-database-id",
title=[{"type": "text", "text": {"content": "Updated Title"}}],
properties={
"New Property": {"rich_text": {}}
}
)
2. Query Databases
Basic Query:
# Query all items
curl -s -X POST "https://api.notion.com/v1/databases/DATABASE_ID/query" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2022-06-28" \
-H "Content-Type: application/json" \
-d '{}' | jq '.results'
# Query with filter
curl -s -X POST "https://api.notion.com/v1/databases/DATABASE_ID/query" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2022-06-28" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"property": "Status",
"select": {
"equals": "In Progress"
}
}
}' | jq '.results'
# Query with sort
curl -s -X POST "https://api.notion.com/v1/databases/DATABASE_ID/query" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2022-06-28" \
-H "Content-Type: application/json" \
-d '{
"sorts": [
{
"property": "Due Date",
"direction": "ascending"
}
]
}' | jq '.results'
Python - Query Operations:
# Simple query
results = notion.databases.query(database_id="your-database-id")
for page in results["results"]:
props = page["properties"]
name = props["Name"]["title"][0]["plain_text"] if props["Name"]["title"] else "Untitled"
print(f"- {name}")
# Query with filter
results = notion.databases.query(
database_id="your-database-id",
filter={
"property": "Status",
"select": {
"equals": "In Progress"
}
}
)
# Query with multiple filters (AND)
results = notion.databases.query(
database_id="your-database-id",
filter={
"and": [
{
"property": "Status",
"select": {"equals": "In Progress"}
},
{
"property": "Priority",
"select": {"equals": "High"}
}
]
}
)
# Query with OR filter
results = notion.databases.query(
database_id="your-database-id",
filter={
"or": [
{"property": "Status", "select": {"equals": "To Do"}},
{"property": "Status", "select": {"equals": "In Progress"}}
]
}
)
# Query with sorting
results = notion.databases.query(
database_id="your-database-id",
sorts=[
{"property": "Priority", "direction": "ascending"},
{"property": "Due Date", "direction": "ascending"}
]
)
# Paginated query
def query_all_pages(database_id, filter=None):
"""Query all pages with pagination"""
all_results = []
has_more = True
start_cursor = None
while has_more:
response = notion.databases.query(
database_id=database_id,
filter=filter,
start_cursor=start_cursor,
page_size=100
)
all_results.extend(response["results"])
has_more = response["has_more"]
start_cursor = response.get("next_cursor")
return all_results
all_items = query_all_pages("your-database-id")
print(f"Total items: {len(all_items)}")
3. Filter Syntax Reference
Text Filters:
# Text property filters
{"property": "Name", "title": {"equals": "Exact Match"}}
{"property": "Name", "title": {"does_not_equal": "Not This"}}
{"property": "Name", "title": {"contains": "partial"}}
{"property": "Name", "title": {"does_not_contain": "exclude"}}
{"property": "Name", "title": {"starts_with": "Prefix"}}
{"property": "Name", "title": {"ends_with": "suffix"}}
{"property": "Name", "title": {"is_empty": True}}
{"property": "Name", "title": {"is_not_empty": True}}
# Rich text property
{"property": "Notes", "rich_text": {"contains": "keyword"}}
Number Filters:
{"property": "Amount", "number": {"equals": 100}}
{"property": "Amount", "number": {"does_not_equal": 0}}
{"property": "Amount", "number": {"greater_than": 50}}
{"property": "Amount", "number": {"less_than": 100}}
{"property": "Amount", "number": {"greater_than_or_equal_to": 10}}
{"property": "Amount", "number": {"less_than_or_equal_to": 99}}
{"property": "Amount", "number": {"is_empty": True}}
{"property": "Amount", "number": {"is_not_empty": True}}
Date Filters:
{"property": "Due Date", "date": {"equals": "2025-01-17"}}
{"property": "Due Date", "date": {"before": "2025-01-20"}}
{"property": "Due Date", "date": {"after": "2025-01-10"}}
{"property": "Due Date", "date": {"on_or_before": "2025-01-17"}}
{"property": "Due Date", "date": {"on_or_after": "2025-01-01"}}
{"property": "Due Date", "date": {"is_empty": True}}
{"property": "Due Date", "date": {"is_not_empty": True}}
# Relative date filters
{"property": "Due Date", "date": {"past_week": {}}}
{"property": "Due Date", "date": {"past_month": {}}}
{"property": "Due Date", "date": {"past_year": {}}}
{"property": "Due Date", "date": {"next_week": {}}}
{"property": "Due Date", "date": {"next_month": {}}}
{"property": "Due Date", "date": {"next_year": {}}}
{"property": "Due Date", "date": {"this_week": {}}}
Select/Multi-Select Filters:
# Select
{"property": "Status", "select": {"equals": "Done"}}
{"property": "Status", "select": {"does_not_equal": "Done"}}
{"property": "Status", "select": {"is_empty": True}}
{"property": "Status", "select": {"is_not_empty": True}}
# Multi-select
{"property": "Tags", "multi_select": {"contains": "urgent"}}
{"property": "Tags", "multi_select": {"does_not_contain": "archived"}}
{"property": "Tags", "multi_select": {"is_empty": True}}
{"property": "Tags", "multi_select": {"is_not_empty": True}}
Checkbox Filters:
{"property": "Completed", "checkbox": {"equals": True}}
{"property": "Completed", "checkbox": {"equals": False}}
Relation and Rollup Filters:
# Relation
{"property": "Project", "relation": {"contains": "page-id"}}
{"property": "Project", "relation": {"does_not_contain": "page-id"}}
{"property": "Project", "relation": {"is_empty": True}}
{"property": "Project", "relation": {"is_not_empty": True}}
# Rollup (depends on rollup type)
{"property": "Total Tasks", "rollup": {"number": {"greater_than": 5}}}
{"property": "Completion", "rollup": {"number": {"equals": 100}}}
Compound Filters:
# AND
{
"and": [
{"property": "Status", "select": {"equals": "In Progress"}},
{"property": "Priority", "select": {"equals": "High"}},
{"property": "Due Date", "date": {"before": "2025-02-01"}}
]
}
# OR
{
"or": [
{"property": "Status", "select": {"equals": "To Do"}},
{"property": "Status", "select": {"equals": "In Progress"}}
]
}
# Nested (AND with OR)
{
"and": [
{
"or": [
{"property": "Priority", "select": {"equals": "High"}},
{"property": "Priority", "select": {"equals": "Medium"}}
]
},
{"property": "Status", "select": {"does_not_equal": "Done"}}
]
}
4. Page Operations
Create Pages:
# Create page in database
curl -s -X POST "https://api.notion.com/v1/pages" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2022-06-28" \
-H "Content-Type: application/json" \
-d '{
"parent": {"database_id": "DATABASE_ID"},
"properties": {
"Name": {
"title": [{"text": {"content": "New Task"}}]
},
"Status": {
"select": {"name": "To Do"}
},
"Priority": {
"select": {"name": "High"}
},
"Due Date": {
"date": {"start": "2025-01-20"}
}
}
}' | jq
Python - Page Operations:
# Create page in database
new_page = notion.pages.create(
parent={"database_id": "your-database-id"},
properties={
"Name": {
"title": [{"text": {"content": "New Task"}}]
},
"Status": {
"select": {"name": "To Do"}
},
"Priority": {
"select": {"name": "High"}
},
"Due Date": {
"date": {"start": "2025-01-20", "end": "2025-01-25"}
},
"Tags": {
"multi_select": [
{"name": "development"},
{"name": "urgent"}
]
},
"Assignee": {
"people": [{"id": "user-id"}]
},
"Notes": {
"rich_text": [{"text": {"content": "Task description here"}}]
},
"Completed": {
"checkbox": False
},
"Amount": {
"number": 100
},
"URL": {
"url": "https://example.com"
},
"Email": {
"email": "user@example.com"
}
}
)
print(f"Created page: {new_page['id']}")
# Create page with content (blocks)
new_page = notion.pages.create(
parent={"database_id": "your-database-id"},
properties={
"Name": {"title": [{"text": {"content": "Page with Content"}}]}
},
children=[
{
"object": "block",
"type": "heading_2",
"heading_2": {
"rich_text": [{"type": "text", "text": {"content": "Overview"}}]
}
},
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{"type": "text", "text": {"content": "This is the content."}}]
}
},
{
"object": "block",
"type": "to_do",
"to_do": {
"rich_text": [{"type": "text", "text": {"content": "Task item"}}],
"checked": False
}
}
]
)
# Retrieve page
page = notion.pages.retrieve(page_id="page-id")
print(f"Page: {page['properties']['Name']['title'][0]['plain_text']}")
# Update page properties
notion.pages.update(
page_id="page-id",
properties={
"Status": {"select": {"name": "Done"}},
"Completed": {"checkbox": True}
}
)
# Archive page (soft delete)
notion.pages.update(
page_id="page-id",
archived=True
)
# Restore page
notion.pages.update(
page_id="page-id",
archived=False
)
5. Block Operations
Block Types:
# Paragraph
{
"type": "paragraph",
"paragraph": {
"rich_text": [{"type": "text", "text": {"content": "Text content"}}]
}
}
# Headings
{
"type": "heading_1",
"heading_1": {
"rich_text": [{"type": "text", "text": {"content": "Heading 1"}}]
}
}
# Also: heading_2, heading_3
# Bulleted list
{
"type": "bulleted_list_item",
"bulleted_list_item": {
"rich_text": [{"type": "text", "text": {"content": "List item"}}]
}
}
# Numbered list
{
"type": "numbered_list_item",
"numbered_list_item": {
"rich_text": [{"type": "text", "text": {"content": "Item 1"}}]
}
}
# To-do
{
"type": "to_do",
"to_do": {
"rich_text": [{"type": "text", "text": {"content": "Task"}}],
"checked": False
}
}
# Toggle
{
"type": "toggle",
"toggle": {
"rich_text": [{"type": "text", "text": {"content": "Toggle header"}}],
"children": [] # Nested blocks
}
}
# Code block
{
"type": "code",
"code": {
"rich_text": [{"type": "text", "text": {"content": "print('hello')"}}],
"language": "python"
}
}
# Quote
{
"type": "quote",
"quote": {
"rich_text": [{"type": "text", "text": {"content": "Quote text"}}]
}
}
# Callout
{
"type": "callout",
"callout": {
"rich_text": [{"type": "text", "text": {"content": "Important note"}}],
"icon": {"emoji": "💡"}
}
}
# Divider
{
"type": "divider",
"divider": {}
}
# Table of contents
{
"type": "table_of_contents",
"table_of_contents": {}
}
Python - Block Operations:
# Get page blocks (children)
blocks = notion.blocks.children.list(block_id="page-id")
for block in blocks["results"]:
print(f"Block type: {block['type']}")
# Append blocks to page
notion.blocks.children.append(
block_id="page-id",
children=[
{
"object": "block",
"type": "heading_2",
"heading_2": {
"rich_text": [{"type": "text", "text": {"content": "New Section"}}]
}
},
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [
{"type": "text", "text": {"content": "Some "}},
{"type": "text", "text": {"content": "bold"}, "annotations": {"bold": True}},
{"type": "text", "text": {"content": " text."}}
]
}
},
{
"object": "block",
"type": "bulleted_list_item",
"bulleted_list_item": {
"rich_text": [{"type": "text", "text": {"content": "First item"}}]
}
},
{
"object": "block",
"type": "bulleted_list_item",
"bulleted_list_item": {
"rich_text": [{"type": "text", "text": {"content": "Second item"}}]
}
}
]
)
# Update block
notion.blocks.update(
block_id="block-id",
paragraph={
"rich_text": [{"type": "text", "text": {"content": "Updated content"}}]
}
)
# Delete block
notion.blocks.delete(block_id="block-id")
# Get all blocks recursively
def get_all_blocks(block_id):
"""Recursively get all blocks"""
all_blocks = []
has_more = True
start_cursor = None
while has_more:
response = notion.blocks.children.list(
block_id=block_id,
start_cursor=start_cursor,
page_size=100
)
for block in response["results"]:
all_blocks.append(block)
if block.get("has_children"):
children = get_all_blocks(block["id"])
all_blocks.extend(children)
has_more = response["has_more"]
start_cursor = response.get("next_cursor")
return all_blocks
all_blocks = get_all_blocks("page-id")
print(f"Total blocks: {len(all_blocks)}")
6. Rich Text Formatting
Rich Text Structure:
# Basic text
{"type": "text", "text": {"content": "Plain text"}}
# Styled text
{
"type": "text",
"text": {"content": "Styled text"},
"annotations": {
"bold": True,
"italic": False,
"strikethrough": False,
"underline": False,
"code": False,
"color": "red" # default, gray, brown, orange, yellow, green, blue, purple, pink, red
}
}
# Link
{
"type": "text",
"text": {
"content": "Click here",
"link": {"url": "https://example.com"}
}
}
# Mention user
{
"type": "mention",
"mention": {
"type": "user",
"user": {"id": "user-id"}
}
}
# Mention page
{
"type": "mention",
"mention": {
"type": "page",
"page": {"id": "page-id"}
}
}
# Mention date
{
"type": "mention",
"mention": {
"type": "date",
"date": {"start": "2025-01-17"}
}
}
# Equation
{
"type": "equation",
"equation": {"expression": "E = mc^2"}
}
Python - Rich Text Helper:
def create_rich_text(text, bold=False, italic=False, code=False, color="default", link=None):
"""Helper to create rich text objects"""
rt = {
"type": "text",
"text": {"content": text},
"annotations": {
"bold": bold,
"italic": italic,
"strikethrough": False,
"underline": False,
"code": code,
"color": color
}
}
if link:
rt["text"]["link"] = {"url": link}
return rt
# Usage
paragraph_content = [
create_rich_text("This is "),
create_rich_text("bold", bold=True),
create_rich_text(" and "),
create_rich_text("italic", italic=True),
create_rich_text(" text with a "),
create_rich_text("link", link="https://example.com"),
create_rich_text(".")
]
notion.blocks.children.append(
block_id="page-id",
children=[{
"type": "paragraph",
"paragraph": {"rich_text": paragraph_content}
}]
)
7. Relations and Rollups
Create Related Databases:
# Create Projects database
projects_db = notion.databases.create(
parent={"type": "page_id", "page_id": "parent-page-id"},
title=[{"type": "text", "text": {"content": "Projects"}}],
properties={
"Name": {"title": {}},
"Status": {
"select": {
"options": [
{"name": "Active", "color": "green"},
{"name": "Completed", "color": "gray"}
]
}
}
}
)
# Create Tasks database with relation to Projects
tasks_db = notion.databases.create(
parent={"type": "page_id", "page_id": "parent-page-id"},
title=[{"type": "text", "text": {"content": "Tasks"}}],
properties={
"Name": {"title": {}},
"Status": {
"select": {
"options": [
{"name": "To Do", "color": "gray"},
{"name": "Done", "color": "green"}
]
}
},
"Project": {
"relation": {
"database_id": projects_db["id"],
"single_property": {}
}
}
}
)
# Add rollup to Projects for task count
notion.databases.update(
database_id=projects_db["id"],
properties={
"Task Count": {
"rollup": {
"relation_property_name": "Tasks", # This is auto-created
"rollup_property_name": "Name",
"function": "count"
}
}
}
)
# Create task linked to project
notion.pages.create(
parent={"database_id": tasks_db["id"]},
properties={
"Name": {"title": [{"text": {"content": "Task 1"}}]},
"Status": {"select": {"name": "To Do"}},
"Project": {"relation": [{"id": "project-page-id"}]}
}
)
8. Search API
Search Operations:
# Search all
results = notion.search()
print(f"Total accessible items: {len(results['results'])}")
# Search with query
results = notion.search(query="project plan")
for item in results["results"]:
obj_type = item["object"]
if obj_type == "page":
title = item["properties"].get("title", {}).get("title", [{}])[0].get("plain_text", "Untitled")
elif obj_type == "database":
title = item["title"][0]["plain_text"] if item["title"] else "Untitled"
print(f"{obj_type}: {title}")
# Search only pages
results = notion.search(
query="meeting",
filter={"property": "object", "value": "page"}
)
# Search only databases
results = notion.search(
filter={"property": "object", "value": "database"}
)
# Search with sorting
results = notion.search(
query="report",
sort={
"direction": "descending",
"timestamp": "last_edited_time"
}
)
# Paginated search
def search_all(query=None, filter=None):
"""Search with pagination"""
all_results = []
has_more = True
start_cursor = None
while has_more:
response = notion.search(
query=query,
filter=filter,
start_cursor=start_cursor,
page_size=100
)
all_results.extend(response["results"])
has_more = response["has_more"]
start_cursor = response.get("next_cursor")
return all_results
Complete Examples
Example 1: Task Management System
#!/usr/bin/env python3
"""notion_tasks.py - Complete task management with Notion"""
from notion_client import Client
from datetime import datetime, timedelta
import os
notion = Client(auth=os.environ["NOTION_API_KEY"])
class NotionTaskManager:
def __init__(self, database_id):
self.database_id = database_id
def create_task(self, name, status="To Do", priority="Medium",
due_date=None, tags=None, notes=None):
"""Create a new task"""
properties = {
"Name": {"title": [{"text": {"content": name}}]},
"Status": {"select": {"name": status}},
"Priority": {"select": {"name": priority}}
}
if due_date:
properties["Due Date"] = {"date": {"start": due_date}}
if tags:
properties["Tags"] = {
"multi_select": [{"name": tag} for tag in tags]
}
if notes:
properties["Notes"] = {
"rich_text": [{"text": {"content": notes}}]
}
return notion.pages.create(
parent={"database_id": self.database_id},
properties=properties
)
def get_tasks_by_status(self, status):
"""Get all tasks with given status"""
return notion.databases.query(
database_id=self.database_id,
filter={
"property": "Status",
"select": {"equals": status}
}
)
def get_overdue_tasks(self):
"""Get all overdue tasks"""
today = datetime.now().strftime("%Y-%m-%d")
return notion.databases.query(
database_id=self.database_id,
filter={
"and": [
{"property": "Due Date", "date": {"before": today}},
{"property": "Status", "select": {"does_not_equal": "Done"}}
]
}
)
def get_high_priority_tasks(self):
"""Get high priority incomplete tasks"""
return notion.databases.query(
database_id=self.database_id,
filter={
"and": [
{"property": "Priority", "select": {"equals": "High"}},
{"property": "Status", "select": {"does_not_equal": "Done"}}
]
},
sorts=[
{"property": "Due Date", "direction": "ascending"}
]
)
def complete_task(self, page_id):
"""Mark task as done"""
return notion.pages.update(
page_id=page_id,
properties={
"Status": {"select": {"name": "Done"}},
"Completed": {"checkbox": True}
}
)
def update_task_status(self, page_id, status):
"""Update task status"""
return notion.pages.update(
page_id=page_id,
properties={
"Status": {"select": {"name": status}}
}
)
def get_weekly_summary(self):
"""Get summary for the week"""
week_ago = (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d")
# Completed this week
completed = notion.databases.query(
database_id=self.database_id,
filter={
"and": [
{"property": "Status", "select": {"equals": "Done"}},
{"property": "Last edited time", "date": {"after": week_ago}}
]
}
)
# Due this week
next_week = (datetime.now() + timedelta(days=7)).strftime("%Y-%m-%d")
upcoming = notion.databases.query(
database_id=self.database_id,
filter={
"and": [
{"property": "Due Date", "date": {"on_or_before": next_week}},
{"property": "Status", "select": {"does_not_equal": "Done"}}
]
}
)
return {
"completed_count": len(completed["results"]),
"upcoming_count": len(upcoming["results"]),
"completed": completed["results"],
"upcoming": upcoming["results"]
}
# Usage
if __name__ == "__main__":
tm = NotionTaskManager("your-database-id")
# Create task
task = tm.create_task(
name="Review Q1 report",
priority="High",
due_date="2025-01-20",
tags=["work", "quarterly"],
notes="Review and provide feedback"
)
print(f"Created task: {task['id']}")
# Get overdue tasks
overdue = tm.get_overdue_tasks()
print(f"\nOverdue tasks: {len(overdue['results'])}")
for t in overdue["results"]:
name = t["properties"]["Name"]["title"][0]["plain_text"]
print(f" - {name}")
# Weekly summary
summary = tm.get_weekly_summary()
print(f"\nWeekly Summary:")
print(f" Completed: {summary['completed_count']}")
print(f" Upcoming: {summary['upcoming_count']}")
Example 2: Content Management System
#!/usr/bin/env python3
"""notion_cms.py - Content management with Notion"""
from notion_client import Client
from datetime import datetime
import os
notion = Client(auth=os.environ["NOTION_API_KEY"])
class NotionCMS:
def __init__(self, content_db_id, categories_db_id=None):
self.content_db_id = content_db_id
self.categories_db_id = categories_db_id
def create_article(self, title, content_blocks, status="Draft",
category=None, tags=None, author=None):
"""Create a new article"""
properties = {
"Title": {"title": [{"text": {"content": title}}]},
"Status": {"select": {"name": status}},
"Created": {"date": {"start": datetime.now().isoformat()}}
}
if category:
properties["Category"] = {"select": {"name": category}}
if tags:
properties["Tags"] = {
"multi_select": [{"name": tag} for tag in tags]
}
if author:
properties["Author"] = {
"rich_text": [{"text": {"content": author}}]
}
return notion.pages.create(
parent={"database_id": self.content_db_id},
properties=properties,
children=content_blocks
)
def create_article_with_template(self, title, template="blog"):
"""Create article from template"""
templates = {
"blog": [
{"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Introduction"}}]}},
{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": ""}}]}},
{"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Main Content"}}]}},
{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": ""}}]}},
{"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Conclusion"}}]}},
{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": ""}}]}},
],
"tutorial": [
{"type": "callout", "callout": {
"rich_text": [{"text": {"content": "Prerequisites: "}}],
"icon": {"emoji": "📋"}
}},
{"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Overview"}}]}},
{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": ""}}]}},
{"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Step 1"}}]}},
{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": ""}}]}},
{"type": "code", "code": {"rich_text": [{"text": {"content": "# code here"}}], "language": "python"}},
{"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Step 2"}}]}},
{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": ""}}]}},
{"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Summary"}}]}},
{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": ""}}]}},
]
}
return self.create_article(
title=title,
content_blocks=templates.get(template, templates["blog"]),
status="Draft"
)
def get_published_articles(self, category=None, limit=10):
"""Get published articles"""
filter_conditions = [
{"property": "Status", "select": {"equals": "Published"}}
]
if category:
filter_conditions.append(
{"property": "Category", "select": {"equals": category}}
)
return notion.databases.query(
database_id=self.content_db_id,
filter={"and": filter_conditions} if len(filter_conditions) > 1 else filter_conditions[0],
sorts=[{"property": "Created", "direction": "descending"}],
page_size=limit
)
def publish_article(self, page_id):
"""Publish an article"""
return notion.pages.update(
page_id=page_id,
properties={
"Status": {"select": {"name": "Published"}},
"Published Date": {"date": {"start": datetime.now().isoformat()}}
}
)
def export_article_to_markdown(self, page_id):
"""Export article content to markdown"""
page = notion.pages.retrieve(page_id)
blocks = notion.blocks.children.list(block_id=page_id)
title = page["properties"]["Title"]["title"][0]["plain_text"]
markdown = f"# {title}\n\n"
for block in blocks["results"]:
markdown += self._block_to_markdown(block)
return markdown
def _block_to_markdown(self, block):
"""Convert block to markdown"""
block_type = block["type"]
if block_type == "paragraph":
text = self._rich_text_to_markdown(block["paragraph"]["rich_text"])
return f"{text}\n\n"
elif block_type == "heading_1":
text = self._rich_text_to_markdown(block["heading_1"]["rich_text"])
return f"# {text}\n\n"
elif block_type == "heading_2":
text = self._rich_text_to_markdown(block["heading_2"]["rich_text"])
return f"## {text}\n\n"
elif block_type == "heading_3":
text = self._rich_text_to_markdown(block["heading_3"]["rich_text"])
return f"### {text}\n\n"
elif block_type == "bulleted_list_item":
text = self._rich_text_to_markdown(block["bulleted_list_item"]["rich_text"])
return f"- {text}\n"
elif block_type == "numbered_list_item":
text = self._rich_text_to_markdown(block["numbered_list_item"]["rich_text"])
return f"1. {text}\n"
elif block_type == "code":
text = self._rich_text_to_markdown(block["code"]["rich_text"])
lang = block["code"]["language"]
return f"```{lang}\n{text}\n```\n\n"
elif block_type == "quote":
text = self._rich_text_to_markdown(block["quote"]["rich_text"])
return f"> {text}\n\n"
elif block_type == "divider":
return "---\n\n"
return ""
def _rich_text_to_markdown(self, rich_text):
"""Convert rich text array to markdown"""
result = ""
for rt in rich_text:
text = rt.get("text", {}).get("content", "")
annotations = rt.get("annotations", {})
if annotations.get("bold"):
text = f"**{text}**"
if annotations.get("italic"):
text = f"*{text}*"
if annotations.get("code"):
text = f"`{text}`"
if annotations.get("strikethrough"):
text = f"~~{text}~~"
link = rt.get("text", {}).get("link")
if link:
text = f"[{text}]({link['url']})"
result += text
return result
# Usage
if __name__ == "__main__":
cms = NotionCMS("your-content-database-id")
# Create article from template
article = cms.create_article_with_template(
title="Getting Started with Python",
template="tutorial"
)
print(f"Created article: {article['id']}")
# Get published articles
published = cms.get_published_articles(limit=5)
print(f"\nPublished articles: {len(published['results'])}")
# Export to markdown
md = cms.export_article_to_markdown("article-page-id")
print(md)
Example 3: Project Dashboard
#!/usr/bin/env python3
"""notion_dashboard.py - Project dashboard with Notion"""
from notion_client import Client
from datetime import datetime, timedelta
import os
notion = Client(auth=os.environ["NOTION_API_KEY"])
def generate_project_dashboard(projects_db_id, tasks_db_id):
"""Generate project dashboard data"""
# Get all active projects
projects = notion.databases.query(
database_id=projects_db_id,
filter={
"property": "Status",
"select": {"equals": "Active"}
}
)
dashboard_data = []
for project in projects["results"]:
project_id = project["id"]
project_name = project["properties"]["Name"]["title"][0]["plain_text"]
# Get tasks for this project
tasks = notion.databases.query(
database_id=tasks_db_id,
filter={
"property": "Project",
"relation": {"contains": project_id}
}
)
# Calculate metrics
total_tasks = len(tasks["results"])
completed = sum(1 for t in tasks["results"]
if t["properties"]["Status"]["select"]["name"] == "Done")
in_progress = sum(1 for t in tasks["results"]
if t["properties"]["Status"]["select"]["name"] == "In Progress")
# Get overdue tasks
today = datetime.now().strftime("%Y-%m-%d")
overdue = sum(1 for t in tasks["results"]
if t["properties"].get("Due Date", {}).get("date", {}).get("start", "9999-99-99") < today
and t["properties"]["Status"]["select"]["name"] != "Done")
dashboard_data.append({
"project_id": project_id,
"project_name": project_name,
"total_tasks": total_tasks,
"completed": completed,
"in_progress": in_progress,
"pending": total_tasks - completed - in_progress,
"overdue": overdue,
"completion_rate": round(completed / total_tasks * 100, 1) if total_tasks > 0 else 0
})
return dashboard_data
def create_dashboard_page(parent_page_id, dashboard_data):
"""Create a dashboard page with metrics"""
# Build blocks for dashboard
blocks = [
{
"type": "heading_1",
"heading_1": {
"rich_text": [{"text": {"content": f"Project Dashboard - {datetime.now().strftime('%Y-%m-%d')}"}}]
}
},
{
"type": "divider",
"divider": {}
}
]
for project in dashboard_data:
blocks.extend([
{
"type": "heading_2",
"heading_2": {
"rich_text": [{"text": {"content": project["project_name"]}}]
}
},
…(truncated)