EvernoteDevelopersevernote.com
Deprecated

Getting Started with the Evernote API

Sharing (and Un-Sharing) Notes

How to start and stop sharing a single note, as well as how to retrieve a list all of the shared notes in an Evernote account.

  • Single Note Sharing

    Single notes can be shared in one of two ways: publicly (using a public note URL) or via email. The latter isn’t exactly sharing as much as it is emailing a copy of a note, so we’re going to focus on the former: sharing via a public shared URL. Note that there isn’t a way to share a single note with only one other person; anybody who knows the URL for a shared note will be able to view it.

    In order to share a single note, you’ll need the following information:

    • The GUID of the note you’d like to share.
    • The ID of the Shard that houses the note to be shared.
    • A valid authentication token or developer token.
    • Initialized instances of NoteStore.Client and UserStore.Client

    The Shard ID can be determined at runtime by querying the UserStore:

    main.py
    def getUserShardId(authToken, userStore):
	"""
	Get the User from userStore and return the user's shard ID
	"""
	try:
		user = userStore.getUser(authToken)
	except (Errors.EDAMUserException, Errors.EDAMSystemException), e:
		print "Exception while getting user's shardID:"
		print type(e), e
		return None
	
	if hasattr(user, 'shardId'):
		return user.shardId
	return None

    Assuming all of that is in place, sharing a note is actually quite simple. By calling NoteStore.shareNote and passing a valid authentication token and the GUID of the note you’d like to share. In return, you’ll get a Share Key from the Evernote Cloud API that can be used in conjunction with the note GUID to view a read-only version of the note.

    Here’s a snippet of code that illustrates how the whole process works:

    main.py
    def shareSingleNote(authToken, noteStore, userStore, noteGuid, shardId=None):
	"""
	Share a single note and return the public URL for the note
	"""
	if not shardId:
		shardId = getUserShardId(authToken, userStore)
		if not shardId:
			raise SystemExit

	try:
		shareKey = noteStore.shareNote(authToken, noteGuid)
	except (EDAMNotFoundException, EDAMSystemException, EDAMUserException), e:
		print "Error sharing note:"
		print type(e), e
		return None

	return "%s/shard/%s/sh/%s/%s" % \
		(EN_URL, shardId, noteGuid, shareKey)

    Assuming nothing broke, the above function will return a public note URL that looks something like this:

    https://sandbox.evernote.com/shard/s1/sh/36dd7123-12c0-457a-a6d0-75555fcc7770/3afc29de3493d0d333b54cf1822be92c

    The last two pieces of data in the URL are the note GUID and the share key.

  • Stop Sharing a Note

    This is about as close to a one-liner as you can get.

    You’ll need an initialized NoteStore.Client instance, a good authentication token and the GUID of the note in question. With those things in place, it’s as simple as calling NoteStore.stopSharingNote:

    main.py
    def stopSharingSingleNote(authToken, noteStore, noteGuid):
	try:
		noteStore.stopSharingNote(authToken, noteGuid)
	except (EDAMNotFoundException, EDAMSystemException, EDAMUserException), e:
		print "Error stopping sharing note:"
		print type(e), e
		return None
	return noteGuid
  • Listing All Shared Notes in an Account

    To search for all of the shared notes in a user’s account, we need to create a NoteFilter object and set its words member to sharedate:* (indicating that the note is shared and we don’t care when). Here’s a function that retrieves all of the shared notes in a user’s account (up to an arbitrary maximum of 500 notes):

    main.py
    def getAllSharedNotes(authToken, noteStore, maxCount=None):
	noteFilter = NoteStore.NoteFilter()
	noteFilter.words = "sharedate:*"
	sharedNotes = []
	offset = 0
	if not maxCount:
		maxCount = 500
	while len(sharedNotes) < maxCount:
		try:
			noteList = noteStore.findNotes(authToken, noteFilter, offset, 50)
			sharedNotes += noteList.notes
		except (EDAMNotFoundException, EDAMSystemException, EDAMUserException), e:
			print "Error getting shared notes:"
			print type(e), e
			return None

		if len(sharedNotes) % 50 != 0:
			## We've retrieved all of the notes 
			break
		else:
			offset += 50
	return sharedNotes[:maxCount]

    After creating and populating our NoteFilter instance, we repeatedly call NoteStore.findNotes, asking for 50 notes each time, collecting the responses into a sharedNotes collection. Once we hit our maximum number of notes or our sharedNotes collection is no longer evenly divisible by 50 (indicating that we received less than 50 notes during the most recent call to NoteStore.findNotes), we return sharedNotes.