New functionality in Evernote API - findRelated (): search for related notes

Not so long ago, at the Evernote Trunk Conference event in San Francisco, we announced a new API NoteStore.findRelated function that independent developers and partners can use. As the name of the function suggests, it allows customers to request notes, notepads and tags that are somehow related to the source data (such input data can be either the identifier of another note, or plain text).



The idea is that Evernote will be more useful if it promptly prompts the user to take notes from his account on the current topic for him. A new API function simplifies the search and presentation of such information. Let's see how this feature works.

')

In Github, you can find an example Python application that uses findRelated . The code below is taken from this application, so if you wish, you can go directly to it.



Let's say that you have already authenticated with the Evernote Cloud API, and you have a note that you would like to use as an initial request. Then the query will be implemented like this:







In addition to our authorization token (both the developer token for testing and the token obtained through OAuth), we will need to create and fill two objects that we will pass as parameters in the findRelated : RelatedQuery and RelatedResultSpec .

RelatedQuery

This class allows us to specify what exactly (a separate note or a block of text) we want to use as source data for searching for related notes. In the above fragment, we specifically indicated an undefined parameter argument, which can be either a note or a string. When defining a RelatedQuery , if we have a note as the source data, we will use its GUID. Then, as the first parameter when calling a function (which in our example is called “ parameter ), we will pass an object of type Note, and specify this GUID as the noteGuid attribute of the noteGuid object. If the parameter is not a note, then we consider that it is just a string, and assign its value to the plainText attribute of the plainText object.



It is worth noting here that you can use either plainText or noteGuid ; you cannot use them at the same time or do not use any at all - the server in this case will throw an exception.



Additional information on RelatedQuery is in the API Help .

RelatedResultSpec

RelatedResultSpec allows us to control the type and number of results returned by the Evernote Cloud API when we call findRelated . We can specify one or more of the following parameters:

• maxNotes
• maxNotebooks
• maxTags

Their names are obvious from their names. If we specify the number in maxNotes , we get the corresponding (or fewer) number of notes. Similarly, it works with notebooks and tags. If you do not specify a value for a particular parameter, you will not get the results of the corresponding type.



In our example, we defined only maxNotes . This means that our RelatedResult RelatedResult , returned by findRelated , will not contain notebooks or labels.



Additional information on RelatedResultSpec is in the API Help .

Use cases

This API function can be useful in many situations. In Evernote, we use findRelated in our web clippers for browsers to show users notes from their account that can be thematically linked to the webpage being viewed. The function is also used in “guessing” tags and notebooks when creating a new note from a fragment of a web page.



For example, if you are developing an application that specializes in meeting and meeting notes, findRelated will be useful for quickly viewing notes on meetings similar to the current document. Using findRelated will be appropriate in many cases, and you will be able to significantly increase the usefulness of your application with relatively little effort.

Conclusion

If everything went smoothly, you will receive a RelatedResult object, in our case with 1-3 related notes. These are Note objects, so you can request their name, GUID, metadata, and so on.



The findRelated function findRelated can be found in our API documentation .



For more information on working with our API and other information on developing an application integrated with Evernote, visit our website for developers . And if you have already begun work on such a project, do not forget to take part in our competition and attract the first users with the help of premium subscriptions Evernote .