🐺
Notion API エンドポイント全て使ってみる「Search」編
はじめに
今回は、Notion API の Search を利用する機会があったので
備忘録も兼ねてSearch周りのエンドポイントについて
基本的な使い方をまとめてみました。
対象
- Notion API を普段から利用している方
- Notion API の詳細が気になるけど調べるのが面倒な方
- Notion API でどんな機能があるのか気になる方
概要
Notion API では様々なエンドポイントが用意されています。
その中でも今回は「Search」に関する機能にフォーカスを当てまとめていきます。
※APIの実行はPostman経由で行います。
Notion API とは
Notion API は、Notion プラットフォームでのデータの読み取り、作成、更新、削除を行うための公式のプログラムインターフェースです。
Notion のデータを外部アプリケーションやスクリプトと連携させることが可能になります。
詳細情報については、公式の Notion API ドキュメントを参照してください。
Searchで用意されているエンドポイント
Searchは、Notion上の統合・共有されているすべての親または子ページとデータベースを検索します。
以降はエンドポイントに関する概要と
Notion上の画面を合わせながらまとめていきます。
Search by title
エンドポイントの概要
- クエリパラメータに入力されたタイトルを持つ、重複したリンクデータベースを除くすべてのページまたはデータベースを返します。
- クエリパラメータを指定しなかった場合は、統合と共有されているすべてのページまたはデータベースを返します。
- ページのみの検索やデータベースのみの検索に制限するには、
filterパラメータを使用する。
リクエスト例
取得するために用意したDatabase
Request例
curl -X POST 'https://api.notion.com/v1/search' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H 'Content-Type: application/json' \
-H 'Notion-Version: 2022-06-28' \
--data '{
"query":"Notion API > プロパティについて",
"filter": {
"value": "page",
"property": "object"
},
"sort":{
"direction":"descending",
"timestamp":"last_edited_time"
},
"page_size": 3
}'
※検索をするにあたり、page_sizeを指定しましたが、指定しないと部分一致のpageも検索対象となるため
わかりやすくするために今回も受けております。
Response例
{
"object": "list",
"results": [
{
"object": "page",
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"created_time": "2024-0x-0xT00:00:00.000Z",
"last_edited_time": "2024-0x-0xT00:00:00.000Z",
"created_by": {
"object": "user",
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"last_edited_by": {
"object": "user",
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"cover": null,
"icon": null,
"parent": {
"type": "database_id",
"database_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"archived": false,
"in_trash": false,
"properties": {
"タグ": {
"id": "t%7DAS",
"type": "multi_select",
"multi_select": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "tag3",
"color": "pink"
}
]
},
"最終更新日時": {
"id": "wWNE",
"type": "last_edited_time",
"last_edited_time": "2024-0x-0xT00:00:00.000Z"
},
"名前": {
"id": "title",
"type": "title",
"title": [
{
"type": "text",
"text": {
"content": "Notion API >プロパティについて",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "Notion API >プロパティについて",
"href": null
}
]
}
},
"url": "https://...",
"public_url": null
},
{
"object": "page",
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"created_time": "2024-0x-0xT00:00:00.000Z",
"last_edited_time": "2024-0x-0xT00:00:00.000Z",
"created_by": {
"object": "user",
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"last_edited_by": {
"object": "user",
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"cover": null,
"icon": null,
"parent": {
"type": "database_id",
"database_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"archived": false,
"in_trash": false,
"properties": {
"タグ": {
"id": "t%7DAS",
"type": "multi_select",
"multi_select": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "tag1",
"color": "orange"
}
]
},
"最終更新日時": {
"id": "wWNE",
"type": "last_edited_time",
"last_edited_time": "2024-0x-0xT00:00:00.000Z"
},
"名前": {
"id": "title",
"type": "title",
"title": [
{
"type": "text",
"text": {
"content": "Notion API > Search みてみる",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "Notion API > Search みてみる",
"href": null
}
]
}
},
"url": "https://...",
"public_url": null
},
{
"object": "page",
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"created_time": "2024-0x-0xT00:00:00.000Z",
"last_edited_time": "2024-0x-0xT00:00:00.000Z",
"created_by": {
"object": "user",
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"last_edited_by": {
"object": "user",
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"cover": null,
"icon": null,
"parent": {
"type": "database_id",
"database_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"archived": false,
"in_trash": false,
"properties": {
"タグ": {
"id": "t%7DAS",
"type": "multi_select",
"multi_select": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "tag2",
"color": "purple"
}
]
},
"最終更新日時": {
"id": "wWNE",
"type": "last_edited_time",
"last_edited_time": "2024-0x-0xT00:00:00.000Z"
},
"名前": {
"id": "title",
"type": "title",
"title": [
{
"type": "text",
"text": {
"content": "Notion API > Errosの概要",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "Notion API > Errosの概要",
"href": null
}
]
}
},
"url": "https://...",
"public_url": null
}
],
"next_cursor": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"has_more": true,
"type": "page_or_database",
"page_or_database": {},
"developer_survey": "https://...",
"request_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Body Paramas
| Params | description | model |
|---|---|---|
| query | The text that the API compares page and database titles against. | string |
| sort | A set of criteria, direction and timestamp keys, that orders the results. The only supported timestamp value is "last_edited_time". Supported direction values are "ascending" and "descending". If sort is not provided, then the most recently edited results are returned first. | object |
| filter | A set of criteria, value and property keys, that limits the results to either only pages or only databases. Possible value values are "page" or "database". The only supported property value is "object". | object |
| start_cursor | A cursor value returned in a previous response that If supplied, limits the response to results starting after the cursor. If not supplied, then the first page of results is returned. Refer to pagination for more details. | string |
| page_size | The number of items from the full list to include in the response. Maximum: 100. | int32 |
Status Code
Search by titleで用意されている Status Code
-
\textcolor{green}{200} success
Response
{
"object": "list",
"results": [
{
"object": "page",
"id": "954b67f9-3f87-41db-8874-23b92bbd31ee",
"created_time": "2022-07-06T19:30:00.000Z",
"last_edited_time": "2022-07-06T19:30:00.000Z",
"created_by": {
"object": "user",
"id": "ee5f0f84-409a-440f-983a-a5315961c6e4"
},
"last_edited_by": {
"object": "user",
"id": "ee5f0f84-409a-440f-983a-a5315961c6e4"
},
"cover": {
"type": "external",
"external": {
"url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
}
},
"icon": {
"type": "emoji",
"emoji": "🥬"
},
"parent": {
"type": "database_id",
"database_id": "d9824bdc-8445-4327-be8b-5b47500af6ce"
},
"archived": false,
"properties": {
"Store availability": {
"id": "%3AUPp",
"type": "multi_select",
"multi_select": []
},
"Food group": {
"id": "A%40Hk",
"type": "select",
"select": {
"id": "5e8e7e8f-432e-4d8a-8166-1821e10225fc",
"name": "🥬 Vegetable",
"color": "pink"
}
},
"Price": {
"id": "BJXS",
"type": "number",
"number": null
},
"Responsible Person": {
"id": "Iowm",
"type": "people",
"people": []
},
"Last ordered": {
"id": "Jsfb",
"type": "date",
"date": null
},
"Cost of next trip": {
"id": "WOd%3B",
"type": "formula",
"formula": {
"type": "number",
"number": null
}
},
"Recipes": {
"id": "YfIu",
"type": "relation",
"relation": []
},
"Description": {
"id": "_Tc_",
"type": "rich_text",
"rich_text": [
{
"type": "text",
"text": {
"content": "A dark green leafy vegetable",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "A dark green leafy vegetable",
"href": null
}
]
},
"In stock": {
"id": "%60%5Bq%3F",
"type": "checkbox",
"checkbox": false
},
"Number of meals": {
"id": "zag~",
"type": "rollup",
"rollup": {
"type": "number",
"number": 0,
"function": "count"
}
},
"Photo": {
"id": "%7DF_L",
"type": "url",
"url": null
},
"Name": {
"id": "title",
"type": "title",
"title": [
{
"type": "text",
"text": {
"content": "Tuscan kale",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "Tuscan kale",
"href": null
}
]
}
},
"url": "https://www.notion.so/Tuscan-kale-954b67f93f8741db887423b92bbd31ee"
}
],
"next_cursor": null,
"has_more": false,
"type": "page_or_database",
"page_or_database": {}
}
-
\textcolor{red}{400} invalid_json
Response
{
"object": "error",
"status": 400,
"code": "invalid_json",
"message": "Error parsing JSON body."
}
-
\textcolor{red}{429} rate_limited
Response
{
"object": "error",
"status": 429,
"code": "rate_limited",
"message": "You have been rate limited. Please try again in a few minutes."
}
Errorコードの詳細は下記ページに記載されています。
さいごに
今回はSearchのエンドポイントについてまとめていきました。
コンテンツが増えてくると、どうしても検索したくなってくるので
Notion上のコンテンツを柔軟に検索することができ
探したいコンテンツをシュッと取得できるのは直感的で嬉しいなと思いました。
一方で参照できるページが増えてくるとレスポンスが膨大になるため
ある程度取得できる件数は絞り込んでも良いかなという印象ですね。
他プロパティに関する追加や更新に関する仕様についても
詳しくみていければと思います。
Discussion