Query pages now in Beta!

Query pages now in Beta!

  • Comments 5

Hi guys,

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:

  1. 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.
  2. 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.
  3. 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.

  1. [GET] https://www.onenote.com/api/beta/pages - Returns the first 20 pages a user has access to ordered by creation time desc (the default ordering).
  2. [GET] https://www.onenote.com/api/beta/pages?$skip=20&$top=100 - Returns pages 21 to 120. You can use skip and top to page through results and increase page size. The maximum page size is 100.
  3. [GET] https://www.onenote.com/api/beta/pages?$filter=contains(title, 'Seattle') - Returns the first 20 pages containing "seattle" or "Seattle" in the title. String comparisons are case insensitive.
  4. [GET] https://www.onenote.com/api/beta/pages?$filter=createdTime gt 2014-01-23 &$skip=20 - Returns pages 21 to 40 the user has saved to OneNote since Jan 23, 2014.
  5. [GET] https://www.onenote.com/api/beta/section/{id}/pages - Returns the first 20 pages under a specific section. You can get a list of section IDs with the following request: [GET] https://www.onenote.com/api/beta/sections.
  6. [GET] https://www.onenote.com/api/beta/pages?$select=id,title&$orderby=title asc - Returns the id and the title only the first 20 pages ordered alphabetically by title

The response is a collection of page objects in JSON format with the following structure :

{
   "@odata.context":"https://www.onenote.com/api/Beta/$metadata#pages",
   "value":[
      {
         "createdTime":"2014-06-12T19:33:41.089Z",
         "links":{
            "oneNoteClientUrl":{
               "href":"onenote:https://d.docs.live.net/…"
            },
            "oneNoteWebUrl":{
               "href":"https://onedrive.live.com/…"
            }
         },
         "id":"{some page id}",
         "parentSection":{
            "id":"{some section id}",
            "name":"Unfiled Notes",
            "links":{
               "href":"https://www.onenote.com/api/Beta/sections/{sectionId}"
            }
         },
         "parentNotebook":{
            "id":"{some notebook id}",
            "name":"Personal (Web)",
            "links":{
               "href":"https://www.onenote.com/api/Beta/notebooks/{notebookId}"
            }
         },
         "title":"Hello World!",
         "createdByAppId":"WLID-{some app id}"
      }
   ]
}

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.

 


  1. Get a client ID for use with the OneNote API.
  2. Get a Windows Store developer account and register you app with the Windows Store.
  3. Install and add a reference to the Live SDK within your project.
 1: using Microsoft.Live;
 2:  
 3:
 4:  
 5: private async void QueryPages()
 6: {
 7:    var client = new LiveAuthClient();
 8:    var loginResult = await client.LoginAsync(new string[] { 
 9:              "wl.signin", 
 10:              "office.onenote" });
 11:  
 12:    if (loginResult.Status == LiveConnectSessionStatus.Connected)
 13:    {
 14:       using (var httpClient = new HttpClient())
 15:       {
 16:          HttpRequestMessage request = new HttpRequestMessage(
 17:                      HttpMethod.Get, "https://www.onenote.com/api/beta/pages");
 18:          request.Headers.Add("Authorization", "Bearer " + loginResult.Session.AccessToken);
 19:          var response = await httpClient.SendAsync(request);
 20:          var content = response.Content.ReadAsStringAsync();
 21:       }
 22:    }
 23: }

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.

- Omar

Leave a Comment
  • Please add 4 and 2 and type the answer here:
  • Post
  • This is awesome!

  • It seems like parentNotebook, parentSection and parentSectionGroup concepts have disappeared. I guess such changes are expected in beta but wanted to make sure if they are gone for good or they will come back at some point. It would be quite useful to know as I am building an SDK and the change breaks my integration tests.

  • Hi Cem,

    Yes. Parent navigation properties are coming back soon. We thought it would be a better idea to make them available as part of supporting the $expand verb across the API. Expand will allow apps to optimize their API calling patterns by requesting properties from multiple entity types in a single RT. Stay tuned.

  • Is it possible to get page's content in html format ?

  • @mpiu: Yes, it is possible to get the page's content in html format. Check out the newest Beta feature: blogs.msdn.com/.../new-beta-api-page-recall.aspx

Page 1 of 1 (5 items)