Here at the OneNote API Team we continue working through our feature backlog as fast as possible to bring new APIs to you. Today we are happy to announce we just added support for querying OneNote pages in Beta! You can now call the API to query the pages a user has access to regardless of which notebook or section they are in. Yes, this includes querying for pages in both notebooks owned by and shared with the user in a single call. For instance, you can now use the API to:
Build a list view of pages a user has saved to OneNote via your app and allow them to open the page in OneNote or OneNote Online.
Build a "Save to OneNote" location picker that gives users full context of their notebook hierarchy (notebooks-> section groups-> sections-> pages) when choosing a save location.
Query for pages containing a keyword or phrase in the title. For instance, a news app that saves articles to OneNote could use the API to allow users to search for articles that read "Seattle" in the headline.
We know there are important scenarios that require retrieving the contents of the page. We are working on this as we speak and will be announcing it pretty soon. We also know there are apps out there that just want to make it easy for users to get to the content they saved to OneNote within the context of the app and now they can do just that.
So how do you get started? The easiest way is to type your queries below or use the OneNote API Apigee console. You can quickly get an idea of the shape of the API without writing a line of code.
The OneNote API is built on the OData v4 standard which means that if you are already familiar with OData you don't have to learn a new query language to query pages in OneNote. You can expect OData verbs and functions like $filter, $orderby, and $select to just work. Here are a few page queries you can try out. They are all vanilla HTTP GET requests.
Supported properties, verbs, operators and functions
For this beta release, we are making the following properties available which you can query using OData syntax (we will be adding more properties soon):
Page ID
Page Title
Page Created time
Page CreatedByAppId - This is the Windows Live Client ID of the app that created the page
Page link
Page OneNote Client link
Page OneNote Online link
Parent notebook ID
Parent notebook name
Parent notebook link
Parent section ID
Parent section name
Parent section link
And below is the list of OData operators, verbs and functions (more are coming as well):
Verbs: $filter, $orderby, $select, $top, $skip
Operator
Description
Example
Comparison Operators
eq
Equal
createdByAppId eq '{AppID}'
ne
Not equal
title ne 'Foo'
gt
Greater than
createdTime gt 2014-02-23
ge
Greater than or equal
createdTime ge 2014-05-05T07:00:00Z
lt
Less than
createdTime lt 2014-02-23
le
Less than or equal
createdTime le 2014-02-23
Logical Operators
and
Logical and
createdTime le 2014-01-30 and createdTime gt 2014-01-23
or
Logical or
createdByAppId eq 'foo' or createdByAppId eq 'bar'
not
Logical negation
not contains(title,'foo')
Function
Example
String Functions
contains
contains(title,'foobar')
endswith
endswith(title,'bar')
startswith
startswith(title,'foo')
length
length(title) eq 19
indexof
indexof(title,'foobar') eq 1
substring
substring(title,1) eq 'foobar'
tolower
tolower(title) eq 'foobar'
toupper
toupper(title) eq 'FOOBAR'
trim
trim(title) eq 'foobar'
concat
concat(title,'- by MyRecipesApp') eq 'Carrot Cake Recipe - by MyRecipesApp'
OAuth scopes
We are introducing 3 new OAuth scopes that you can request within your apps to be able to query pages in OneNote.
office.onenote - Grants read permissions to the user's notebooks and pages. Request this scope if your app needs to query pages in any of the user's notebooks.
office.onenote_update_by_app - Grants create, read, update, and delete permissions to pages created by the app. Request this scope if your app only needs to query pages the user created through your app.
office.onenote _update - Grants full access to the user's notebooks and pages. Request this scope if your app needs to query pages in any of the user's notebooks.
If you notice the actual OneNote REST API is super simple to use. Authorizing the request is perhaps the one tricky thing. We don't want you to spend any time writing boiler plate code so we have posted a few code samples (for all major platforms) on GitHub that take care of this for you so you can get right to business. You can also use the code snippets below if you want to quickly try this within an existing app.
Help us make it better
As with the rest of our API features in Beta, we want you to try page queries out in your apps and give us feedback. Tell us what tweaks you think we should make to simplify your code, what things are missing to complete your scenario, what are the things you like that we should leave untouched, and if you think we just got it plain wrong we want to hear that too :)! Help us make the API better for you and the rest of the OneNote developer community so once it sticks it sticks for good. We are planning to leave this feature in Beta for at least one month (possibly more) for you to try it out and post your suggestions. We will iterate on your feedback and release to production soon after.
Please post your recommendations as comments to this post. for feature requests you can add to the list or vote on UserVoice. Finally, if you have any problems with the OneNote API in general please post your questions to stackoverflow.
Look out for more updates coming soon and happy coding.