This is a multi-part tutorial series on using Gravatar from AppleScript to update your Mac Address Book pictures automatically. These pictures then sync to your iPhone for Gravatar goodness on the go.

I’ve had some AppleScripts to work with Gravatars and Address Book hanging around in rough form for quite a while. But I was recently prompted to clean them up and write these tutorials when Matt Mullenweg posted about Gravatar on his blog saying that “we need a better way to get Gravatars into your Apple address book / iPhone.” I hope that the documentation and tools from this project will be used for other creative Gravatar integration projects.

We’re about to put all of what we learned in part 1, part 2, and part 3 together to make our working script. Be sure to check out the previous parts for the details of how it all works.

Here is the process the script will be doing:

1. Get a list of only the selected contacts from Address Book. This way we can control which contacts get their pictures updated if we don’t want them all.
2. Ask the user if we should overwrite any existing pictures or skip those contacts.
3. Step through each of those contacts and get all of the e-mail addresses associated with each.
4. Step through each e-mail address and download its Gravatar to a temporary file. If there is more than one address with a Gravatar we’ll keep it simple and just let it set each one in turn and we’ll end up with last one found. This could be improved in the future to favor a particular one if needed.
5. Update the Address Book picture, delete the temporary file, then repeat the process with the next contact.

Here’s the script: (Open in Script Editor)

-- Set selected Address Book contact pictures from Gravatar.
-- Released under GPL.
-- by Doug Smith, http://smithsrus.com
 
 
-- Grab the selected records and see how many there are.
tell application "Address Book"
	set selected_contacts to selection
	set count_selected to number of items in selected_contacts
 
	-- Bail out if there are no records selected. Otherwise ask about how to deal 
	-- with contacts having existing pictures.
	if count_selected < 1 then
		tell me to display dialog "You must first select some Address Book contacts." buttons {"Cancel"} default button 1 cancel button 1
	else
		if count_selected = 1 then
			set plural to ""
		else
			set plural to "s"
		end if
		tell me to set user_result to display dialog "We're about to try updating " & count_selected & " selected Address Book contact picture" & plural & " from Gravatar. Would you like to overwrite existing pictures or skip those contacts?" buttons {"Cancel", "Overwrite Existing", "Skip Existing"} cancel button 1 default button 1 with icon caution
		set overwrite to (button returned of user_result contains "Overwrite")
	end if
 
	-- Step through each contact and find Gravatars.
	with timeout of 600 seconds
		repeat with one_contact in selected_contacts
			if not ((image of one_contact exists) and not overwrite) then
 
				-- Step through the contact's e-mail addresses.
				set all_emails to emails of one_contact
				repeat with one_email_record in all_emails
					set one_email_address to value of one_email_record
 
					set grav_file to (my get_gravatar(my trim_email(one_email_address)))
 
					-- If we have a Gravatar image add it to the contact.
					if grav_file is not "" then
						set image of one_contact to my get_pict_data(grav_file)
					end if
				end repeat
			end if
		end repeat
	end timeout
	tell me to display dialog "Done. You may need to select a different record to force Address Book to refresh the screen before changes show." buttons {"Okay"} default button 1
end tell
 
 
-- Trim junk off the end of the e-mail address field. Assume space separated.
on trim_email(email_address)
	set AppleScript's text item delimiters to " "
	return item 1 of email_address
end trim_email
 
 
-- Look up a Gravatar from an e-mail address and save to a file.
on get_gravatar(email_address)
	-- Calculate an MD5 for the e-mail address.
	set md5_email to do shell script "md5 -q -s `echo " & email_address & " | tr '[:upper:]' '[:lower:]'`"
 
	-- Construct the Gravatar URL. Max Address Book picture size stored is 218 pixels.
	set grav_url to quoted form of ("http://gravatar.com/avatar/" & md5_email & "?s=218&d=" & "%22%22" as text)
 
	-- Make a file name in which to temporarily save the Gravatar.
	set grav_file to (path to temporary items) & "gravatar" & md5_email & ".jpg" as text
	set grav_POSIX_file to quoted form of POSIX path of grav_file
 
	-- Download the Gravatar image to the temporary file with a timeout of 10 seconds.
	do shell script "curl " & grav_url & " -m 10 -o " & grav_POSIX_file
 
	tell application "System Events"
		if exists file grav_file then
			return grav_file
		else
			return ""
		end if
	end tell
end get_gravatar
 
-- Read the picture data into a variable in TIFF format then delete the file.
on get_pict_data(grav_file)
	tell application "System Events"
		set file_ref to open for access grav_file
		set pict_data to read file_ref as "TIFF"
		close access file_ref
 
		delete file grav_file
		return pict_data
	end tell
end get_pict_data

There you have it. I have some ideas to take it further but I’ll let everyone test what we have and offer feedback before continuing. I’ll also make an easier to use application download for everyone once we’ve done enough testing to work out the kinks.

We’re on our way to building an AppleScript to update all of the contacts in your Mac Address Book with pictures from the Gravatar service. This is part 3 of the series.

Part 1, Gravatar, AppleScript, and Address Book Pictures, introduced the topic and ended with a short AppleScript to construct a Gravatar URL given an e-mail address.

Then in part 2, Setting an Address Book Picture with AppleScript, we built a script showing how to successfully set a contact photo in Address Book.

Now we need to detect when the Gravatar service does not have an image on file for a given e-mail address. The problem is that Gravatar does one of several things when it doesn’t have a matching image: return a default image, return an image you specify, or generate an image in one of several styles. But in every case it returns an image.

This is all well and good if you’re displaying Gravatars on a blog comments page. The Gravatar URL ends up inside an img tag and this keeps it dead simple. It’s also nice for everyone to get some kind of avatar even if they haven’t created one.

But for our purposes we don’t need a default image that ends up being attached to a contact. Not only does it clutter our contacts, but it would make it more difficult if we later wanted our script to only update contacts with no existing picture and leave the others alone.

Detecting a no match condition would also be useful in a WordPress plugin even if a default image was used. For example, I’ve always wanted to display some sort of indicator and a link to Gravatar for those who don’t have a Gravatar yet. If we can detect that a default image was used then we can set a CSS class on the image or do other creative things.

So how do we tell if there is no image match? It’s simple with a little undocumented trick in the Gravatar URL.

There is a d= parameter where we can specify a default image to return when there is no match. If we set that to null by using two empty URL encoded quotes then instead of a default image we get nothing. For example:

For our Address Book script we need to save the image to a file anyway so we just check for the existence of the file or a zero size. We can skip that entry or take other action if there is nothing there.

In the case of a WordPress plugin it might be less convenient because we may have to hit the Gravatar servers twice; once to check for a no match condition, then again to get the image with whatever default we actually want. Of course, if we use a local default file then it would still only be one call to the Gravatar service but that rules out using one of the cool generated defaults.

(If any of the Gravatar folks are listening, it would be great to have an option in the URL that means I’m using this for further processing and not in an img tag then also pass back some sort of status telling if the image is a default.)

Here’s a demonstration AppleScript that makes use of the above technique to download a Gravatar for a given e-mail address and take action only if there was a matched image: (Open in Script Editor)

(Updated with a small bug fix on 03/25/2009.)
(Updated on 04/23/2009 to remove my testing e-mail address and display the downloaded file path.)

-- Download a Gravatar image and see if it's a match or default.
-- Released under GPL.
-- by Doug Smith, http://smithsrus.com
 
-- The e-mail address to look up.
set email to "someone@somewhere.com"
 
-- Calculate an MD5 for the e-mail address.
set md5_email to do shell script "md5 -q -s `echo " & email & " | tr '[:upper:]' '[:lower:]'`"
 
-- Construct the Gravatar URL.
set grav_url to quoted form of ("http://gravatar.com/avatar/" & md5_email & "?d=" & "%22%22" as text)
 
-- Make a file name in which to temporarily save the Gravatar.
set grav_file to (path to temporary items) & "gravatar" & md5_email & ".jpg" as text
set grav_POSIX_file to quoted form of POSIX path of grav_file
 
-- Download the Gravatar image to the temporary file with a timeout of 10 seconds.
do shell script "curl " & grav_url & " -m 10 -o " & grav_POSIX_file
 
tell application "System Events"
	if exists file grav_file then
		tell me to display dialog "Yes, we have a matching Gravatar downloaded to " & grav_POSIX_file & "." buttons {"Okay"} default button 1
		delete file grav_file
	else
		tell me to display dialog "Sorry, there was no matching Gravatar." buttons {"Okay"} default button 1
	end if
end tell

Well, we’re almost to our goal of a script to automatically update all of our Address Book contacts with Gravatars. I’ll put it all together next time in part 4.

In part 1, Gravatar, AppleScript, and Address Book Pictures, we covered the basics of getting a Gravatar URL with AppleScript. The end goal is to automatically update all of our Address Book pictures with Gravatars in one fell swoop.

There are a couple tricky things we need to solve to reach our goal. They aren’t difficult; just not well documented, if at all.

In this post I’ll show you how to update a contact picture with AppleScript.

Let’s get started.

We know from the Gravatar documentation that it returns images in jpeg format. Now according to the AppleScript dictionary for Address Book, the person class has an image element that is in TIFF format. So we’ll have to convert the image.

In addition, Address Book is very particular about how it gets an image. The only way I could make it work was to have the actual TIFF picture data loaded into a variable then set the contact’s picture to that. I couldn’t just refer to a file, even if it was already a TIFF.

Fortunately, there’s no need to go through a big conversion script or call on other applications. You can simply open a jpeg file from AppleScript and read the contents into a variable while coercing it to TIFF format.

Here is a demonstration script showing how it works: (Open in Script Editor)

-- Set an Address Book contact photo from a jpeg file.
-- Released under GPL.
-- by Doug Smith, http://smithsrus.com
--
-- This is for demonstration purposes. It only works on the first selected
-- contact in Address Book and contains little error checking. Note that
-- the picture displayed will not change until you select a different record
-- then come back to the original record so it can refresh.
 
tell application "Address Book"
	set AB_contacts to selection
 
	if number of items in AB_contacts = 1 then
		set one_contact to item 1 of AB_contacts
 
		set pict_file to choose file of type "JPEG" with prompt "Choose a jpeg file"
		open for access pict_file
		set pict_data to read pict_file as "TIFF"
		close access pict_file
 
		set image of one_contact to pict_data
	end if
end tell

It’s worth noting that my attempts to get the picture data into a variable Address Book accepted by means other than reading a file were not successful. For example, I tried using a shell call to curl to download a file and return the results to a variable. That would have been nice for our purpose of downloading a Gravatar image. If anyone has any further insight on that please let me know.

That’s all for this post. Stay tuned for part 3 when I’ll cover Detecting When Gravatar Has No Image to Match an E-mail Address. Then in part 4 we’ll put it all together with a Script to Update Address Book Contacts with Gravatar Images.

I’ve always been a fan of adding photos to the people in my Mac Address Book application. It’s a nice personal touch when the photo appears on e-mail messages from people I know. And now that I have an iPhone, those photos sync to the phone and show up in my contacts and when I get calls.

But wouldn’t it be nice if we could add photos to our contacts without doing them all manually? Well, that’s where Gravatar and a little AppleScript will do the job.

For those not familiar with Gravatar, it’s a free avatar service from the nice folks who make WordPress. You register your e-mail address with the service and upload an avatar picture to go with it. Your avatar then automatically shows up on all sorts of blogs and forums where you post or comment, and can be put to use for other services as well.

We should be able to use AppleScript to step through our contacts, grab the e-mail address, retrieve the Gravatar, and add the picture to the contact. The Gravatar implementor’s guide has useage instructions and lots of examples, but nothing for AppleScript. So let’s start with an AppleScript in the same style as the other implementer’s guide examples. (I won’t be covering how Gravatars work since it is so well documented. See How the URL is constructed for details.)

AppleScript doesn’t have built-in commands for calculating md5, converting text to lowercase, and url encoding, which we need. Instead of writing all of that code, we can cheat a little and call the equivalent commands from the OS X shell.

Here’s the basic process:

1. Change the e-mail address to lowercase.
2. md5 encode the e-mail address.
3. url encode the default image URL.
4. Slap it all together to make a Gravatar image URL.

And here is the script to do it: (Open in Script Editor)

-- Make a Gravatar URL from an e-mail address.
-- Released under GPL.
-- by Doug Smith, http://smithsrus.com
 
-- The e-mail address to look up.
set email to "someone@somewhere.com"
 
-- Set a few defaults.
property grav_default : "http://somewhere.com/homestar.jpg"
property grav_size : 40
 
-- Encode the elements as needed.
set md5_email to do shell script "md5 -q -s `echo " & email & " | tr '[:upper:]' '[:lower:]'`"
set encode_default to do shell script "echo " & grav_default & " | perl -MURI::Escape -lne 'print uri_escape($_)'"
 
-- Construct the Gravatar URL.
set grav_url to "http://gravatar.com/avatar/" & md5_email & "?d=" & encode_default & "&s=" & grav_size as text

This is getting a bit long so I’m going to break it into multiple parts.

In part 2 I’ll cover how to set an Address Book picture from AppleScript and how to detect if Gravatar doesn’t have an image for an address instead of ending up with a default image we don’t want. Both of those are a little tricky so it will likely fill that post. Part 3 will put it all together to automatically update pictures for the whole address book.

I changed my mind and decided to make the parts into smaller posts covering some of the individual tasks. I’m hoping this will make it easier for others to find these solutions for use in their own projects.

Part 2: Setting an Address Book Picture with AppleScript
Part 3: Detecting When Gravatar Has No Image to Match an E-mail Address
Part 4: Putting it all together with a Script to Update Address Book Contacts with Gravatar Images.

I have some ideas to take it further that may end up in a couple more posts. Please stay tuned and let me know what you think. I’ll construct the remaining posts based on feedback.