You are here

Hierarchical Keywords Expansion Using AppleScript in Aperture 3

Scott Davenport's picture
May 9, 2014 - 9:00pm

Aperture 3 supports hierarchical keywords and I love them. Taking a little time up front to organize your keywords hierarchically speeds up your workflow. Tagging images is boring, albeit necessary to help people (and search engines) find your photos.

Hierarchical Keywords in a nutshell

Understanding hierarchical keywords is best explained with an example. A few months ago I was in Austin, Texas and shot a bunch of photos. I added the city “Austin” to my keywords as shown here:

An example of a hierarchical keyword structure

When assigning keywords, I explicitly assigned only the “Austin” keyword. The rest of keywords in the hierarchy — “Texas”, “United States”, “North America”, and “Place” — were implicitly applied by Aperture. 

Now, when I search for photos with the keyword “Texas”, the results include all photos from “Austin”. And “Dallas”, and “Houston”, and so on. Aperture understands the keyword hierarchy and shows me the photos I expect to see.

Location hierarchies are intuitive for most people. I also have hierarchies for all sorts of subjects and descriptions. Examples include Occupations, Nature, Architectural Features, Human Emotions, and Immediate Family.

So far, so good. All sunshine and double rainbows. Fewer keywords to assign, a faster workflow. However…

The export caveat

Aperture fully understands hierarchical keywords. The important words in that last sentence are Aperture understands. Other applications do not. When a version or original is exported, only the explicitly assigned to the photo are included in the exported image. Put another way, only the tags in the Keywords metadata field will be in your exported image. In the example below, the keywords are limited to “Austin”, “Bridges”, “Landscape”, “Outdoor”, “River”, and “Rocks”.

Only explicitly added keywords are included in exported images

This is a problem for images shared on photography sites such as 500px or Flickr. The additional keywords increase the visibility of your photos and improve the changes of someone finding your photos. In my example, anyone searching for “Texas” photos will not find my shot. Not good.

So what to do? Manually assigning all keywords in the hierarchy is more time consuming. Lifting and stamping the keywords is an option, although you still spend the up front time applying loads of keywords to the initial image. For one or two images, that may be acceptable, but it doesn't scale to larger projects.

The best of both worlds

I didn't want to give up on using hierarchical keywords. The keyword step of my workflow is very streamlined. So, I wrote an AppleScript to expand the keywords when I need it. It's called… wait for it… Expand Hierarchical Keywords. Ok, so I don't have a future in marketing.

The script walks through the keywords assigned to an image and “flattens” them to include the parents as explicitly assigned keywords. Select one or more photos to expand, run the script, and you're set. After running the script against my bridge photo above I have a wider set of keywords now.

A handle AppleScript will expand Aperture’s hierarchical keywords for you

You can see the script in action here:

The script offers a few customizations:

  • Turn on/off the creation of a new version for expanding keywords (default is on)
  • Specify a keyword blacklist for keywords you do not want applied (in my example, “Place” isn't a very meaningful keyword to apply, so that a candidate for the blacklist)
  • Flag the image(s) with expanded keywords (default, no flag)
  • Set a color label to the image with expanded keywords (default, no change to the color label)

I personally keep version creation turned on. The versions with the expanded keywords are transitory. Once I've exported and shared to online portfolios, those versions are deleted. The latter two customizations make it easier to locate the images modified by the script.

This does add a step in my workflow, however only for images that I post to photography sites. Yet it's automated, quick, and meshes well with further workflow steps. When the script completes, the images with the expanded keywords are automatically selected ready for the next step in your workflow. 

You can download the script for free from or download it directly by clicking here.

EDITOR'S NOTE: If you haven't used an AppleScript in Aperture before, you'll need to enable some preferences in the AppleScript Editor for the script menu to show up. You can download the free instructions for all the scripts sold on ApertureExpert here, which will tell you everything you need to know to install.

About the author, Scott Davenport:

I'm a San Diego based photo educator and landscape photographer and can't get enough of the ocean. I teach workshops, write books and create videos about photography. I'm also much more comfortable behind the camera than in front of it.

See more of my work at

Apple Aperture
Scott Davenport

Scott,  Thanks for a very great tip/article.  I downloaded your free AppleScript (thanks again!).  I recently took a series of photos in Las Vegas, and used Las Vegas as my keyword on import and used both it and NV in the location and state on my import metadata.  When I applied your script to a photo, it did indeed generate a new version, but Nevada, North America, etc did not appear in the info window of that version.  Is there another setting that I need to set to tell Aperture to understand  when I type Las Vegas??  Also, anyone using AppleScripts for the first time will need to go into System Preferences>Security & Privacy>Privacy>Accessibility and select “SystemUIServer” to tell Mac OSX to allow the script to run.



Florian Cortese


That whole hierarchy of ​North America > Nevada > Las Vegas would have been manually created by Scott, not something that the script is going to automatically look up. And AFAIK it's not pulling data out of other metadata fields, just the keywords.

As an example, if you had Animalia > Reptilia > Lizard as a hierarchical keyword set, and only applied “Lizard”, his script would then auto-complete both “Reptilia” and “Animalia” for you. If on the other hand your hierarchy was Creepy Crawlies > Lizard, it'd pull out “Creepy Crawlies”, but it's not going to look up the kingdom names.

Thanks for the reminder on setup/install. I'll amend the post to include that.

— Have you signed up for the mailing list?

Joseph has it right (as usual:). The keyword groups must be setup prior to running the script. And yes, the script is only reading the keywords field. 

I see two possible new scripts one could write. One to cleanup (delete) the “extra” versions that have explicit keywords applied. If they all use a common naming scheme, that would be pretty easy. A smart group to find them would probably be as easy, I guess. A second would be to go through the location fields of all one’s photos and insure there is a heirarchical keyword set for all of those locations. IPTC metadata includes country, state, city and location. Country, state and city fields seem like good candidates for creating the heirarchy in Keywords, and an optional task would be to assign the leaf keyword (city) as an explicit keyword.

One of the really nice features of MediaPro (was iView Media Pro, then Microsoft Expressions Media, now PhaseOne Media Pro) is that it creates some automatic “smart groups” using heirarchical dates and locations. And with the locations, you can drag and drop sets of images onto a location and MediaPro automatically fills in the IPTC metadata location fields for you. Makes me wonder if one could have a action associated with assigning a keyword that could then fill in the location fields for you. Drag-n-drop a leaf location from your heirarchical keywords, and two things end up happening: keyword assigned, AND IPTC location fields filled in. Hmmm.

Hi Walter,

Interesting idea wrt cleanup. I'm leery of having scripts that delete photos, although rejecting is a good alternative. Something else I've been meaning to fiddle with is using the expand keywords script as part of a larger Automator workflow. The script is a good building block and the “expanded” versions are all selected when the script completes.

My typical usage is expand the keywords, export the “expanded” versions, delete/reject the “expanded” versions. I have a different script I use for exporting versions for sharing and posting to social media. My “expanded” versions are very short lived - I run two scripts and then delete the “expanded” versions.

On the surface, this workflow seems very doable with Automator. I have very little experience with Automator, and it's been quite a long time since I've tinkered with it. I don't know what the gotchas are (there's always one :)

Fantastic, my OCD can’t thank you enough for this!

I have just found this script which works great.  One question though, is it possible to use wildcards in the blacklist?  For example, I have all my keyword group heading and sub headings starting with numbers, so if I could exclude 1*, 2* etc that would save a heap of time setting this up



Hi Anthony,

In a word, yes. The script is software, and software can be changed. For the keyword setup you have, let's assume you setup theBlacklist as follows with the attention of filtering out any keywords starting with the character “1” or “3”.

property theBlacklist: {"1", "3"}

Next,  you want to modify the inBlacklist() routine in the script to return true if the first character of the keyword is a “1” or a “3”. I haven't tested this, but I believe this will work:

on inBlacklist(keyword)
    set firstCharacter to character 1 of keyword
    if theBlacklist contains firstCharacter then
        return true
        return false
    end if
end inBlacklist

This is a custom tweak for your particular keyword hierarchy. And I suspect the current code will break down if you have keywords beginning with double-digit string (ex: “10”, “11”, etc.). 

Hopefully that gets you going. There's plenty of articles on AppleScript string manipulation online to refine things to your specific situation.


I’ve been experimenting with migrating to Lightroom 5.7 using the built in capability.

Of note is that it successfully imports hierarchical keywords so there is no need for this script if you’re going that way.

I actually like LR’s handling of hierarchies better because you can mark some keywords to not be exported – useful for a grouping like “country” – and you can easily see all of the keywords, real and implied.

Hi Allister… I've just begun exploring LR as well and I really like how it handles keywords. I will be very happy not to run my script anymore :)

Just wrote about it here, too. Check out

I’m still cleaning up my Aperture Library, getting ready to migrate to another product and wanted to flatten my keywords by using your script to fill out my keywords. I get the error “This script requires Mac OS GUI Scripting facilities, which is disabled.”  However, I have it enabled. It is checked under System Preferences>Privacy>Accessibility. I’m on Yosemite. Any suggestions?



Please ignore the above post. It works fine when I select at least 1 image. Sorry.


You may login with either your assigned username or your e-mail address.
Passwords are case-sensitive - Forgot your password?