Thumbnails
Retrieving small versions of data stored in Evernote
The Evernote service can produce thumbnail images for notes and individual resources. Thumbnails are not accessed through the Cloud API. Instead, a HTTP POST request is made to the Evernote service. If no resources are attached to the note (i.e. it is note that contains only text) the thumbnail will be a image of the first few lines of text in the note. To retrieve the thumbnail for a note, use the URL:
https://[service]/shard/[shardId]/thm/note/[noteGuid]/
Where:
- [service] is the name of the Evernote service (www.evernote.com)
- [shardId] is the shard ID where the note is stored
- [noteGuid] is the GUID of the note that is being linked to
To retrieve a thumbnail for a single resource, use the URL:
https://[service]/shard/[shardId]/thm/res/[resourceGuid]/
Where [resourceGuid] is the GUID of the resource you wish to retrive the thumbnail of.
Thumbnail Image Type and Size
Thumbnails will be of type PNG, JPEG, or GIF (as indicated by the response "Content-Type" header). You can specify the image format that you want by appending .jpg, .gif, .bmp or .png to the GUID.
Thubmnails will fit within a 300 by 300 pixel square without requiring you to crop or scale them manually. One or both dimensions of an image may be less than the size of the box, so the image should be centered with an appropriate background and/or frame. You can request a smaller thumbnail by passing the size POST parameter with a value from 1 to 299, indicating the desired size of the bounding box in pixels. The server will return an image that will fit within this box, but one or both dimensions may be less than the requested value. The image will look best if the size is an even multiple of 300, such as 150 or 75.
Examples
The following examples access thumbnails for an Evernote account on shard s1 of www.evernote.com. Note that no authentication is required for these examples because the are in a public notebook, and that we're using GET instead of POST to simplify the example.
Get a full-size thumbnail for the note with the GUID e669c090-d8b2-4324-9eae-56bd31c64af7:
https://www.evernote.com/shard/s1/thm/note/e669c090-d8b2-4324-9eae-56bd31c64af7
Get a 75x75 thumbnail for the same note in JPEG format:
https://www.evernote.com/shard/s1/thm/note/e669c090-d8b2-4324-9eae-56bd31c64af7.jpg?size=75
Get a full-size thumbnail for an image resource with GUID 8528dddd-1d71-4e4d-9006-377be7517dfb:
https://www.evernote.com/shard/s1/thm/res/8528dddd-1d71-4e4d-9006-377be7517dfb
Here's how the authenticated POST request might look in the real world:
POST /shard/s1/thm/note/e669c090-d8b2-4324-9eae-56bd31c64af7 HTTP/1.1 | |
Host: www.evernote.com | |
Content-Length: 107 | |
Content-Type: application/x-www-form-urlencoded | |
auth=S%3Ds1%3AU%3D293f%3AE%3Db46cda%3AC%3D12e5d64584d%3AP%3D37%3AA%3Dfred%3AV%3D2%3AH%3D50a022dd072798e19298b5007868cb3 |
Note the inclusion of the auth
POST parameter; this valid authentication token—a developer token would also work here—must be included if the requested note or resource is not shared publicly. Again, for public notes and notebooks, the auth
parameter is not required and should be omitted.
The following is a fully working example that writes all the thumbnails of the notes in a specified notebook to the current directory using Python, Evernote's Python SDK and Requests (a Python library for making HTTP requests):
'''This is a script that writes jpg thumbnails for each note in a specified notebook to the currect directory''' | |
from evernote.api.client import EvernoteClient | |
from evernote.edam.notestore.ttypes import RelatedQuery, NoteFilter, NotesMetadataResultSpec | |
import requests | |
import sys | |
#SET THESE VALUES!!! | |
auth_token = "INSERT DEVELOPER TOKEN HERE" | |
notebook_name = "INSERT DESIRED NOTEBOOK NAME" | |
sandbox = "SET TO True (if on sandbox) or False (if on production)" | |
if auth_token == "INSERT DEVELOPER TOKEN HERE" or notebook_name == "INSERT DESIRED NOTEBOOK NAME" or sandbox == "SET TO True (if on sandbox) or False (if on production)": | |
print "Please specify values for \"auth_token\", \"notebook_name\", and \"sandbox\" in this file: %s." % sys.argv[0] | |
sys.exit(1) | |
#initialize the client, user and notestore | |
client=EvernoteClient(token=auth_token, sandbox=sandbox) | |
note_store=client.get_note_store() | |
user_store=client.get_user_store() | |
#get a list of personal notebooks | |
notebooks = note_store.listNotebooks() | |
#get the selected notebook | |
for notebook in notebooks: | |
if notebook.name == notebook_name: | |
selected_notebook = notebook | |
if not selected_notebook: | |
print "Could not find " | |
#return a list of metadata about the notes in the selected ntoebook. | |
noteFilter = NoteFilter() | |
noteFilter.notebookGuid = selected_notebook.guid | |
spec = NotesMetadataResultSpec() | |
spec.includeTitle = True | |
results = note_store.findNotesMetadata(noteFilter, 0, 100, spec) | |
#set the payload for the requests to get thumbnail | |
payload = {"auth":auth_token} | |
#set Base URL for thumbnail requests | |
if sandbox: | |
URL_BASE="https://sandbox.evernote.com/" | |
else: | |
URL_BASE="https://www.evernote.com/" | |
#get thumbnail for each note in the notebook | |
for note in results.notes: | |
#request for retriving the thumbnail | |
r=requests.post(URL_BASE+"shard/"+user_store.getUser().shardId+"/thm/note/"+note.guid+".jpg", data=payload) | |
if r.status_code == 200: | |
#if the request was successful write the thumbnail to disk | |
f = open(note.title+".jpg", 'w') | |
f.write(r.content) | |
f.close() | |
print "Wrote "+note.title+" thumbnail to disk." | |
else: | |
print "Error retriving thumbnail." | |
print "Returned " + r.status_code + " status code." |