Search

Searching notes and note metadata

Search Basics

Performing a basic search of a user’s Evernote account involves two components:

1. An instance of NoteFilter
2. A call to NoteStore.findNotes

NoteFilter offers several members that can be populated depending on the type of results you’re looking for:

• words — send a text-based search query (e.g.,“notebook:foo tag:bar”).
• notebooksGuid — restrict the search results to a single notebook identified using it’s Notebook.guid value.
• tagGuids — limit your search results to only those notes that are assigned these tags (represented as a collection of Tag.guid strings).
• inactive — marking this member as true will return only inactive notes (notes in the Trash, in other words). If left as false — the default value — only active notes will be returned.

filter = NoteStore.NoteFilter()
filter.words = "created:month-3"
filter.notebookGuid = "SomeNotebookGuidHere"
filter.tagGuids = ["tagGuid1","tagGuid2"]

NoteStore.findNotes takes four parameters, in this order:

1. A valid auth token (a developer token will also work here)
2. An instance of NoteFilter
3. The offset, or index of the first result within all possible results. This is used for retrieving a large number of results using successive calls to findNotes.
4. The number of notes to be retrieved in this request. If there are fewer matching notes than requested, all matching notes will be returned.

If we wanted to retrieve the 100 newest notes in an account, our code might look like this:

filter = NoteStore.NoteFilter()
filter.ascending = False

ourNoteList = noteStore.findNotes(authToken, filter, 0, 100)

As you can see, we create an instance of NoteFilter and set the ascending member to False (so the results are returned in descending order), set our offset to 0 and our limit to 100. If this query results in less than 100 notes, all matching notes will be returned.

findNotes returns a type we haven’t yet seen: NoteList. Feel free to peruse the documentation for this type if you want to learn about everything it contains. In this example, we want to see which notes are returned — those can be find by querying NoteList.notes:

filter = NoteStore.NoteFilter()
filter.ascending = False
ourNoteList = noteStore.findNotes(authToken, filter, 0, 100)

for note in ourNoteList.notes:
    print note.guid

When run, that code will echo the GUID of each matching note to the console.

Metadata Searching

NoteStore.findNotesMetadata allows your app to retrieve metadata about notes in a user’s account without requesting the notes themselves. This can be helpful since metadata searches are generally lighter-weight (in terms of actual bytes being returned).

findNotesMetadata works almost exactly like NoteStore.findNotes with the following exceptions:

1. findNotesMetadata also takes an additional parameter: an instance of NotesMetadataResultSpec, which defines which metadata we’d like returned by findNotesMetadata.
2. findNotesMetadata returns an instance of NotesMetadataList, not NoteList.

Building on our earlier example, assume we wanted to see the parent notebook guids and created dates of the last 100 notes added to an account:

filter = NoteStore.NoteFilter()
filter.ascending = False

rspec = NoteStore.NotesMetadataResultSpec()
rspec.includeNotebookGuid = True
rspec.includeCreated = True

ourMetadataList = noteStore.findNotesMetadata(authToken, filter, 0, 100, rspec)

for metadata in ourMetadataList.notes:
    print metadata.notebookGuid
    print metadata.created