Finding Related Notes
Giving notes context
Recently at the 2012 Evernote Conference, we announced a new API available to third-party developers and partners,
NoteStore.findRelated. As the name implies, this function allows the client to request notes, notebooks and tags that are related to the supplied data (either a specific Note or a block of plain text).
Over on Github, you’ll find an example Python application that uses
findRelated. The code in this post will be boosted directly from the example application, so feel free to follow along and get your hands dirty.
Assuming you’ve already authenticated with the Evernote Cloud API and have a note you’d like to use as the basis for your request, this is what a basic implementation might look like:
Aside from our auth token (either a dev token used during testing or an auth token acquired using OAuth), we need to create and populate two objects that we’ll pass as parameters to
Related Query and
This class allows us to enumerate the thing (a single note or block of text) for which we’d like to see related items. In the above snippet, we’ve defined an intentionally-vague
parameter argument which could be either a Note object or a block of text. When we define our
RelatedQuery, we’ll use either the GUID of our “base note” (assuming
parameter is a Note) and assign it to the
noteGuid member of
RelatedQuery or, if
parameter is something other than a Note, we’ll use it to populate the
plainText field of our
It’s important to note that we must choose either
noteGuid; we can’t use both, nor can we use neither.
(For more information on
RelatedQuery, see the API reference).
RelatedResultSpec gives us control over the types and number of results returned by the Evernote Cloud API when we call
findRelated. We can populate one or more of the following members:
It works how you think it would; if we give a number for
maxNotes, we’ll get that number of notes (or fewer). Same with notebooks and tags. The only caveat is if you don’t provide a value for one or more of these, no results of that type will be returned.
In our example, we only define
maxNotes. This means that our
RelatedResult (the type returned by
findRelated) will not contain any notebooks or tags.
(For more information on
RelatedResultSpec, see the API reference).
In the above implementation—assuming there was at least one note matching our criteria—you’ll have a
RelatedResult object populated with up to three related notes. These are
Note objects, so you can query them for their name, GUID, metadata, etc.
For more information about our API or for developer support, visit our developer site.