{"id":23266789,"url":"https://github.com/daviddebels/notionclient","last_synced_at":"2025-09-12T11:44:09.840Z","repository":{"id":62449135,"uuid":"367702118","full_name":"DavidDeBels/NotionClient","owner":"DavidDeBels","description":"Unofficial iOS/macOS SDK for the Notion API.","archived":false,"fork":false,"pushed_at":"2021-07-05T12:42:28.000Z","size":1138,"stargazers_count":20,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-14T08:53:17.983Z","etag":null,"topics":["ios","macos","notion","notion-api","notion-sdk","objective-c","swift"],"latest_commit_sha":null,"homepage":"","language":"Objective-C","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/DavidDeBels.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-15T18:19:14.000Z","updated_at":"2025-03-21T19:28:47.000Z","dependencies_parsed_at":"2022-11-01T23:17:11.749Z","dependency_job_id":null,"html_url":"https://github.com/DavidDeBels/NotionClient","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/DavidDeBels/NotionClient","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidDeBels%2FNotionClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidDeBels%2FNotionClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidDeBels%2FNotionClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidDeBels%2FNotionClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DavidDeBels","download_url":"https://codeload.github.com/DavidDeBels/NotionClient/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidDeBels%2FNotionClient/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274806184,"owners_count":25353449,"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","status":"online","status_checked_at":"2025-09-12T02:00:09.324Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ios","macos","notion","notion-api","notion-sdk","objective-c","swift"],"created_at":"2024-12-19T16:21:47.193Z","updated_at":"2025-09-12T11:44:09.813Z","avatar_url":"https://github.com/DavidDeBels.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NotionClient: a Notion SDK for iOS \u0026 macOS\n\n\u003cimg src=\"https://github.com/DavidDeBels/NotionClient/raw/main/readme_banner.png\" /\u003e\n\nUnofficial Notion API SDK for iOS \u0026 macOS. This is an alpha version and still work in progress.\n\n## TODO\n\nFeatures:\n- Create new pages in a database (WIP)\n- Make all objects copyable (WIP)\n- Add date \u0026 formula filters\n- Add Foundation objects for blocks / modifying page contents\n\nDocumentation:\n- Add documentation for all methods\n- Add sample project for Objective-C\n- Add sample project for Swift\n\nSupport:\n- Add support for macOS\n- Add support for tvOS\n- Add support for watchOS?\n- Add OAuth2 authorization support? (currently not possible due to limitations in redirect URI)\n\n\n## Introduction\n\nNotionClient is a native iOS \u0026 macOS SDK for [Notion's official API](https://developers.notion.com/). API responses are automatically converted to native Foundation objects making it a lot easier to read the data coming from Notion. Those same Foundation objects can then be modified and sent back to the API to update the objects. Most objects also have convenience initializers for the most common use cases, e.g. setting a text property with just 1 string in 1 color.\n\nThis way, there is never any need to deal with Notion's complex JSON structure directly. \n\n\n## Requirements\n\n- iOS 11 or above\n\n\n## Installation\n\nNotionClient does not use any external dependencies.\n\n### Manually\n\n1. Open NotionClient.xcodeproj\n2. Build the NotionClient-iOS scheme\n3. Copy the generated NotionClient.framework file to your project\n\n### Using CocoaPods\n\nAdd NotionClient to your Podfile and run `pod install`.\n\n```ruby\n# Podfile\nplatform :ios, '11.0'\n\ntarget 'YOUR_TARGET_NAME' do\n    # Dynamic frameworks is supported but not required\n    use_frameworks!\n\t\n    pod 'NotionClient'\nend\n```\n\n## Usage\n\n### Objective-C\n\nImport Notion.h in the implementation files (or in a Prefix header):\n\n```objectivec\n#import \u003cNotionClient/Notion.h\u003e\n```\n\n### Swift\n\nImport Notion.h in the Objective-C Bridging Header:\n\n```objectivec\n// Bridging header\n#import \u003cNotionClient/Notion.h\u003e\n```\n\n## Documentation\n\n### General information\n\nAll communication with the Notion API happens by using a NotionClient object. A NotionClient requires an integration token to be able to communicate with the Notion API, see the [official Authorization guide](https://developers.notion.com/docs/authorization) for more information on how to create an integration and a token. Multiple NotionClient objects can be used, each using different integration tokens.  \n\nOnce initialized a NotionClient object can make requests to the Notion API:\n* All requests to the Notion API are asynchronous and will return the result (or error) in a completion handler. \n* If the request was successful, the response will be returned in the completion handler in the form of one or multiple native objects (e.g. NotionPage or NotionUser). These objects are (often simplified) wrappers around the JSON objects that the Notion API returns. These  exist to simplify reading and writing data from/to the Notion API. It should never be necessary to deal with JSON directly. \n* If the request has failed, an NSError object will be returned in the completion handler. In case of an API error, the error object's code will be the HTTP status code and the response body containing the error message will be in the userInfo dictionary of the error object. \n* Requests that use pagination are handled automatically by default for simplicity sake. If a response indicates that more items are available, a new request will be made to fetch the next page. This means that calling a function on a NotionClient to get a list may do multiple API requests behind the scenes. The completion handler will return the results of all pages. The page size is set to 100 by default (the maximum) but this can be modified. \n* At the moment there is no way to handle paginated requests manually but this will be added in the future.\n\nFor all documentation, visit the \u003ca href=\"https://github.com/DavidDeBels/NotionClient/wiki\" target=\"_blank\"\u003eWiki\u003c/a\u003e.\n\n\n### Creating a NotionClient\n\nCreating a NotionClient is simple, just pass an integration token and you're good to go. \n\nSwift:\n```swift\nlet client = NotionClient.init(token: \"NOTION_INTEGRATION_TOKEN\")\n```\n\nObjective-C:\n```objectivec\nNotionClient *client = [NotionClient clientWithToken:@\"NOTION_INTEGRATION_TOKEN\"];\n```\n\n### Getting all users\n\nTo get all users in the workspace, you can use NotionClient's `getUsers` method. This will return an array of NotionUser objects. From there you can get the user's ID, name, email, etc.\n\nSwift:\n```swift\nclient.getUsers { (users, error) in\n    let user = users?.first\n}\n```\n\nObjective-C:\n```objectivec\n[self.notionClient getUsersWithCompletion:^(NSArray\u003cNotionUser *\u003e * _Nonnull users, NSError * _Nonnull error) {\n    NotionUser *user = users.firstObject;\n}];\n```\n\n### Query a database\n\nTo get pages from a database, you can use NotionClient's `queryDatabase` method. This will return an array of NotionPage objects. From there you can access the page's properties, title, parent, etc.\n\nSwift:\n```swift\nclient.queryDatabase(id: \"DATABASE_ID\") { (pages, error) in\n    let page = pages?.first\n}\n```\n\nObjective-C:\n```objectivec\n[self.notionClient queryDatabaseWithId:@\"DATABASE_ID\" completion:^(NSArray\u003cNotionPage *\u003e * _Nullable pages, NSError * _Nullable error) {\n    NotionPage *page = pages.firstObject;\n}];\n```\n\nOptionally you can provide a NotionFilter and/or an array of NotionSort objects to either filter results or have them return in a specific order or both.\n\nSwift:\n```swift\nlet filter = NotionTextFilter.property(\"Country\", equals: \"Belgium\")\nlet sorts = [\n    NotionSort.descendingOnProperty(name: \"Inhabitants\"),\n    NotionSort.ascendingOnProperty(name: \"City\")\n]\n\nclient.queryDatabase(id: \"DATABASE_ID\", filter: filter, sorts: sorts) { (page, error) in\n    let page = pages?.first\n}\n```\n\nObjective-C:\n```objectivec\nNotionFilter *filter = [NotionTextFilter property:@\"Country\" equals:@\"Belgium\"];\nNSArray *sorts = @[\n    [NotionSort descendingOnProperty:@\"Inhabitants\"],\n    [NotionSort ascendingOnProperty:@\"City\"]\n];\n\n[self.notionClient queryDatabaseWithId:@\"DATABASE_ID\" filter:filter sorts:sorts completion:^(NSArray\u003cNotionPage *\u003e * _Nullable pages, NSError * _Nullable error) {\n    NotionPage *page = pages.firstObject;\n}];\n```\n\nTo use multiple filters, create a NotionFilterGroup object, which is a collection of multiple NotionFilters. A NotionFilterGroup is also a NotionFilter, so groups can be nested up to 2 levels deep. For more information see the [official documentation on Compound Filters](https://developers.notion.com/reference/post-database-query#compound-filters).\n\nSwift:\n```swift\nlet filter = NotionFilterGroup.orGroup(with: [\n    NotionTextFilter.property(\"Country\", equals: \"Belgium\"),\n    NotionFilterGroup.andGroup(with: [\n        NotionCheckboxFilter.property(\"Visited\", equals: true),\n        NotionFilterGroup.orGroup(with: [\n            NotionMultiSelectFilter.property(\"Languages\", contains: \"English\"),\n            NotionFileFilter.propertyIsNotEmpty(\"Flag\")\n        ])\n    ])\n])\n```\n\nObjective-C:\n```objectivec\nNotionFilter *filter = [NotionFilterGroup orGroupWithFilters:@[\n    [NotionTextFilter property:@\"Country\" equals:@\"Belgium\"],\n    [NotionFilterGroup andGroupWithFilters:@[\n        [NotionCheckboxFilter property:@\"Visited\" equals:YES],\n        [NotionFilterGroup orGroupWithFilters:@[\n            [NotionMultiSelectFilter property:@\"Languages\" contains:@\"English\"],\n            [NotionFileFilter propertyIsNotEmpty:@\"Flag\"]\n        ]]\n    ]]\n]];\n```\n\n### More documentation coming soon!\n\n## License\n\nNotionClient is released under an [MIT License](https://opensource.org/licenses/MIT). See LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaviddebels%2Fnotionclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaviddebels%2Fnotionclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaviddebels%2Fnotionclient/lists"}