Better multi-country support in Contacts

By • Published: January 4, 2010 • Last updated: September 1, 2014 • Filed in: Tips & tricks

Here is a free plug-in that I have written for Apple’s Contacts (Address Book) that provides better multi-country support:

  • country names: you no longer have many variations for country names (so: all “United States”, instead of many variations like “USA”, “US”, “United States of America”);
  • country address formats: it tells Contacts to use the formatting that belongs to that country (e.g. my default format is for the Netherlands, which normally means for US addresses that state is missing and zip and city are switched).

Before (left): non-standard country name and incorrect format (state is missing, zip and city are switched)
After (right): standard country name and correct format

Quite useful for those that have contacts in multiple countries. You can specify in the script what countries to check and what your preferred country names are. Missing/unknown countries are added as a group in Contacts.

Simply download and run, or install as plug-in in /Library/Address Book Plug-Ins ~/Library/Application scripts/ (location appears to have changed in 10.9.2.

September 2014: v1.9 introduces progress meter (available in Yosemite), user request added (only process contacts in defined group), bug fixes.

Standard country names

Before I had the script, I had many variations of country names (“United States”, “United States of America”, “USA”, “US”, etc.). For filtering and searching it would be nice to have a standard country name. The script looks for -defined by you- country name aliases and replaces them by the -defined by you- preferred name.

Related, request for Apple: please add filtering for country. I can filter (smart group) based on city, state or zip… but not country. In the mean time I use the generic address filter when I want to create a smart group.

Country address formats

It took me a while to discover the -built in- support for address formats. While in Edit mode, you can click on the address label (e.g. work/home) and then select the Change Address Format. What this does is setting the Country Code field, which is the iso code for that country. Not only is this setting difficult to find, it is a pain to do it if you have many international cards. Plus: if the country is already known, why would you have to do this at all?

This is where the script helps. When you run it, it will look for the regular country field and if it is one of the recognized names then it will set the country code.

Here are a couple of examples of the different country formats (click to enlarge):

Default country format

In the settings you can define your default country format:

Download the script

version: 1.9.1
last updated: 2014-09-02
downloads: 1610
before updating, first copy settings + the country table.

To view the script as text:

AppleScript - *text* - fix country names and formats in Contacts

Revision history:
v1.0, 2010/01/03, initial release
v1.1, 2010/01/04, added result display options, added ability to run as Address Book plugin, Growl support
v1.2, 2010/01/10, added support for all known iso countries, write results to log file for easy copy/paste
v1.2.1, 2010/01/11, small Growl fix for non-Growl users
v1.2.2, 2010/01/12, leave iso code empty in lookup list to overwrite Apple’s format + check small countries if not in large country list
v1.3, 2010/01/12, added support for optional checking of latest version of plug-in
v1.4, 2010/01/15, added support for groups: adds missing/unknown country entries, extra check for problematic cards
v1.5, 2010/02/06, using “iPhone” country list instead of official ISO list, changed default values of some parameters
v1.5.1, 2011/07/28, small fixes, Lion compatibility, changed default values of some parameters
v1.5.2, 2011/08/20, small fixes, growl fix, user request: made preferred country case sensitive
v1.6, 2013/03/31, renamed script, fixed country code for Japan and Czech Republic, speed improvement for searching countries,
fix for read-only accounts (e.g. Facebook), removed Growl to improve Mac OSX compatibility, use optional notification center script, quick install in Terminal: sudo gem install terminal-notifier
v1.7, 2013/10/26, compatibility with Mavericks, use native notifications (10.9 or higher), improved detection of read-only accounts (Facebook etc.)
v1.8, 2014/01/13, user suggestion: create summary of countries per country code
v 1.9, 2014/09/01, Yosemite progress support, user suggestion: only check contacts in a specific group (property check_only_contacts_in_group), bug fixes

How to install & run the script

After downloading the .zip file, double click to unzip. You will now have the Applescript script.

There are two options to run the script:

  • plug-in for Contacts (preferred): install the script in [user home]/Library/Address Book Plug-Ins [user home]/Library/Application scripts/ (per user) or /Library/Address Book Plug-Ins /Library/Application scripts/ (all users). Note: the location has changed since 10.9.2. To use: select an address label (work/home/etc.) and click on “Check all country names and codes”.
  • standalone: save the script anywhere and double-click to open in Apple’s Script Editor. Optionally you can uncomment the log lines to get a detailed log of the actions.

For both (optional): open the script in AppleScript Editor and customize the sections between #### … #### (see customize section). Restart Contacts if you make changes to the settings or table. Run the script as often as you like.


By default (as of version 1.4), you will get feedback in Contacts itself. Two groups will automatically be created and filled with people:

  • that have an address in an unknown country (note that “unknown” can also mean: not in your country table);
  • that have an address, but where the country field is empty.

Note that this is an *add-only* action (and not a “smart group”), it is up to you to clean/remove the groups when you have modified the records.

If you want, you can get a summary at the end (by setting the optional parameter show_results). A summary will be placed on your Desktop and opened in TextEdit.

The unknown country section is ready for copy&paste to the script. Go through the list, modify it the way you like and make sure no “??” iso codes remain.
The missing countries section is FYI, you can update those addresses if you want to. It is the same names that appear in the “without country group”.


The performance depends on the size of your Contacts database and how clean the data is.
E.g. for me it took 81 seconds the first time (656 people checked, 81 country names updated, 480 country formats updated), now it takes about 4 seconds.

Test vcards

If you want to test the script before you let it check all your address book cards, enable the setting in the script and create entries in Address Book with last name “testing”. Instead of creating them yourself, you can also download the test cards I have used.

Example vcards

After testing, you can disable the setting again and delete the cards from your Address Book.

Customize the script

It is up to you to tell the script what country names to look out for.
The structure: iso code, list of preferred name and -if you want- aliases for that country. The bottom of the script has a list of all of the iso country codes and names, in the list at the top you tell it what you want it to look like. Different language, add alternative names/languages, etc. Is the standard entry in the iso list ok with you? Then there is no need to add it to the top list (although, if you do: it will speed up the script).

Note: only use the iso codes from the bottom list of the script, these are the ones that Apple recognizes. Any unknown iso codes will result in Contacts hiding that address (even though the iso code is legal, e.g. “AN” for “Netherlands Antilles”).

This is what the list could look like:

In the script you can set various parameters, the main ones:

  • add_to_groups: (default: true) create groups for entries with missing/unknown countries; is *add-only*, so clean up manually
  • show_results: (default: true) give feedback afterwards -see below-, shows contacts where country field is empty, and countries that are not in your table.

Your own language

Here is a quick example to show how you can set the language.

The first example will look for “Germany” in German and French and use the English version of the country name.

You prefer the German version? Simply make that the first name in the list entry. It will look for all entries “Germany” and “Allemagne” in your Contacts and replace them with “Deutschland”.

You don’t like the format that Apple picks for your iso code? Just pick another iso code or leave the field empty (it will then use your default country format).

66 Responses to “Better multi-country support in Contacts”

  1. Paul says:

    I just downloaded the script to use on my iMac running OS 10.8.2 and it doesn’t work. I installed the script in the ~Library/Address Book Plug-Ins folder. I tried the standalone approach but I receive the error “The document “address book country names and codees.scpt” could not be opened.”

    Any clues on what I am doing wrong?

  2. Gunnar says:

    Hi Winfred,

    Thanks for this fantastic initiative! I am running 10.8.2 here.

    Cannot edit the script in script editor: “The document “address book country names and codes.scpt” could not be opened.”

    The script does run, though. But I don’t see it changing anything:
    I have a lot of addresses with the “A”, “D” in the country field. They didn’t change.
    I have an address with “GB” in the country field. This is marked as an unknown country although I think this is the correct ISO-Code?
    The address format remains the default “Germany” for addresses with correct foreign country codes like “CH”.

    Is there a problem with Mountain Lion? Or am I doing something wrong here?

  3. Eric says:

    Hi Winfred,

    I have been happily using your script for years now. Thanks! I’ve got v. 1.5.1 on OS 10.6.8 (Snow Leopard). I’ve not yet made the leap to Mountain Lion.

    Today I thought maybe I’d try 1.5.2 on my machine and at least I’d not get the reminder every time that there is a newer version available. And the Growl problem might go away.

    However, similarly to what Gunnar noted in October of 2012, when I try to edit the script (v. 1.5.2), I get this message: “Unable to read the file because the script is not editable (it was saved as run-only)”.

    Maybe there is something that needs to be tweaked for 1.5.2? Or is something not quite right on our systems (Gunnar is running 10.8.2, but I’m on 10.6.8).


  4. winfred says:

    Script has been updated. The script is now downloaded as .zip file. This hopefully resolves issues with “unable to read” or “uncompiled” messages. In addition: compatibility and performance enhancements. And Growl support has been replaced with optional terminal-notifier tool, so that people without Growl can compile the script as well.

  5. [...] sito dell’autore dello script è possibile scaricare il piccolo programma inoltre vengono anche fornite ulteriori informazioni [...]

  6. Gam says:

    This is soooo useful! Thank you very much.
    I have one request though, it would be great if we could run it on a selected number of contacts or a group, on top of only 1 or all.

    • winfred says:

      Thanks Gam! I can understand that that is useful. I don’t believe there is a good way to do this. I could program it so it checks in what group that contact is but a contact could be in multiple groups.

      • Gam says:

        yep. Automator has an action to gather selected people in Contacts, I tried to feed them to your script but I’m having problem as the ‘run applescript’ action only accept text, not a file. If I copy your script in there, it doesn’t compile.

        • winfred says:

          There is a manual way that might help. Open the Applescript and look for:
          – “set testing to false” and set this to true
          – “set LocalPeople to”, you will find some examples to select a specific group of contacts, e.g. from a group.

  7. Eerk Hofmeester says:

    Hallo Winfred,

    Thanks very much for sharing this with the community! It saved me a lot of manual updates when sending my New Year cards this year. Small question: in order to find out if I made any typos in country names (and add them to the script for later use) an easy way of listing all variants per country code used in the country fields would be handy.

    Eerk Hofmeester
    “nl”, “Nederland”

Leave a Reply

« | Home | »