Finding Related Notes

Giving notes context

---

The NoteStore.findRelated API 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 findRelated: Related Query and RelatedResultSpec.

RelatedQuery

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 RelatedQuery.

It’s important to note that we must choose either plainText or noteGuid; we can’t use both, nor can we use neither.

(For more information on RelatedQuery, see the API reference).

RelatedResultSpec

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:

• maxNotes
• maxNotebooks
• maxTags

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).

Conclusion

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.

The function definition for findRelated can be found in our API reference documentation. This method is available in all of our SDKs, which can be found on GitHub.