Reading Geolocation
  - Default tags
  - Default input
  - Regular expressions
Writing Geolocation
  - While geotagging
Extra Features
  - Language translations
  - Optional parameters
  - Alternate databases
  - Listing the database
  - Customization

ExifTool Geolocation Feature

ExifTool has the ability to generate geolocation information (including city, region, subregion and country) from GPS coordinates (and visa versa) using an included database of all cities with population 2000 or greater based on a Creative Commons database from geonames.org. (An extended version of the ExifTool database is available with cities down to a population of 500. See below for more information.) There are two basic modes of operation: one to generate geolocation information when reading from a file, and another to write geolocation information to a file.

Reading Geolocation Information

Geolocation tags may be generated when reading a file by setting the API Geolocation option. For example,
exiftool -api geolocation "-geolocation*" test.jpg
produces an output similar to this for a file containing GPS coordinates:
Geolocation City                : Saint-Hyacinthe
Geolocation Region              : Quebec
Geolocation Subregion           : Montérégie
Geolocation Country Code        : CA
Geolocation Country             : Canada
Geolocation Time Zone           : America/Toronto
Geolocation Feature Code        : PPL
Geolocation Population          : 50000
Geolocation Distance            : 1.8 km
Geolocation Bearing             : 226
Geolocation Position            : 45.6307, -72.9571
The above tags are generated based on either a GPS position (preferentially), or from city, state/province and country information. The meanings of the resulting region and subregion tags vary by country. In North America for example, region corresponds to state or province, and subregion corresponds to county. The population is rounded to 2 significant digits, and the distance and bearing are generated only when an input GPS position is provided, and give the distance in km and the compass bearing from the input GPS point to the GeolocationPosition of the returned city. See the Extra Tags documentation for a brief description of each Geolocation tag.

Default tags

The Geolocation option has a list of default tags that it looks for in the source file to use as inputs for determining the nearest city. These tags are, in order:
GPSLatitude, GPSLongitude, GPSLatitudeRef, GPSLongitudeRef, GPSCoordinates, LocationShownGPSLatitude, LocationShownGPSLongitude, XMP:City, State, CountryCode, Country, IPTC:City, Province-State, Country-PrimaryLocationCode, Country-PrimaryLocationName, LocationShownCity, LocationShownProvinceState, LocationShownCountryCode, LocationShownCountryName
First, the file is checked for GPS tags in this list, and coordinates from the first available of these tags are used as inputs to determine the geolocation. If no GPS position is found, the file is checked for city/state/province/country/countrycode tags in the list, and the inputs are taken from the first available city information. Note that each specified city tag must come before the corresponding state/province, etc. If multiple matches are found, the city with the largest population is returned unless the -a (API Duplicates) option is used in which case all matching cities are returned.
To override the default list of tags, set the Geolocation option to a comma-separated list of tags beginning with dollar signs, but note that Composite tags may not be used. For example:
exiftool -api geolocation="$XMP:GPSLatitude,$XMP:GPSLongitude" test.jpg
(Note: On Mac/Linux/PowerShell, use single quotes (') instead of double quotes (") around arguments containing a dollar sign ($).)

Default input

It may be useful to specify a default input for the case where none of the specified tags are found. For this, the default input is added to the Geolocation setting. For example, the information returned by this command includes Geolocation information for the specified coordinates if none of the default tags listed above are found:
exiftool -api geolocation="44.3414,-72,1234" test.jpg
Alternately, default city information may be specified. When doing this, the city name comes first, and is optionally followed by region (eg. state or province), subregion (eg. county), country code and/or country name in any order, separated by commas. For example:
exiftool -api geolocation="London,England" test.jpg
The default tags may be specified at the same time as the default value, for example:
exiftool -api geolocation="$gpslatitude,$gpslongitude,-37.81,144.96" test.jpg
This feature may be used to generate geolocation information with no input file at all. For example, this command:
exiftool -api geolocation=Munich,Germany
produces this output:
Geolocation City                : Munich
Geolocation Region              : Bavaria
Geolocation Subregion           : Upper Bavaria
Geolocation Country Code        : DE
Geolocation Country             : Germany
Geolocation Time Zone           : Europe/Berlin
Geolocation Feature Code        : PPLA
Geolocation Population          : 1300000
Geolocation Position            : 48.1375, 11.5755

Regular expressions

An advanced feature allows standard Perl regular expressions of the form /expr/ to be used to match city, region, etc names. The regular expression may be prefixed by "ci", "re", "sr", "cc" or "co" to apply only to City, Region, Subregion, CountryCode or Country names, otherwise the expression matches any of these. A dash at the start is used to exclude matching entries (eg. -co/Canada/ excludes cities in Canada from the search). The regular expression matches are case sensitive unless "i" is added after the expression. For example:
# this matches "Frontenac" in any place name (case insensitive)
exiftool -api geolocation=/frontenac/i

# while this matches "Frontenac" only in subregion names
exiftool -api geolocation=sr/frontenac/i

# and this matches the city "Kingston" with "Ontario" in any other field
exiftool -api geolocation=kingston,/ontario/i
One more feature allows both GPS and place names to be used together if no input tags are found and the default value includes both of these. In this case the closest city matching all of the specified names is returned. For example, to find the closest city in Canada to a specified location, you could do this:
exiftool -api geolocation="40.784,-73.966,co/Canada/"
This technique may be useful if you were travelling near the border of a country and want to keep the geolocated cities within that country.

Writing Geolocation Information

A write-only Geolocate tag is provided as a convenience to simplify the writing of standard geolocation tags. This is an alternative to using the API Geolocation option and copying the generated Geolocation tags individually to the desired locations, and is completely independent of the API Geolocation setting (although the optional parameters still apply).
Writing the Geolocate tag with GPS coordinates generates city, state/province, country code and country tags. By default, XMP tags are generated, but group name(s) may be specified to write tags to other locations (see table below). For example, to write the XMP City, State, CountryCode and Country tags from specified GPS coordinates:
exiftool "-geolocate=45.6429,-72.9374" test.jpg
or to write the IPTC tags from GPS coordinates in a file:
exiftool "-iptc:geolocate<gpsposition" test.jpg
Conversely, GPS coordinates may be generated by writing Geolocate with a city name. A region, subregion, country code and/or country name may be added in any order after the city name, separated by commas. Fields must match exactly the entries in the database, but case is not significant. Regular expressions may also be used in the same format as for the API Geolocation option (see above). If more than one matching city is found then a minor warning is issued and the tags are not written, but the IgnoreMinorErrors option may be used to write tags for the matching city with the largest population. For example, the following command writes XMP:GPSLatitude, etc and IPTC:City, etc for Paris France.
exiftool -xmp:iptc:geolocate="paris,fr" test.jpg
The table below lists the tags that are written for each group name specified for the Geolocate tag. Multiple group names may be used. In some cases, different tags are written based on whether or not input GPS coordinates or a city name were used.
Group Name(s) SpecifiedTags Written based on input...
GPS coordinatesCity name
(none) XMP:City
XMP:State
XMP:CountryCode
XMP:Country
Keys:LocationName
GPSLatitude
GPSLongitude
GPSLatitudeRef
GPSLongitudeRef
QuickTime::GPSCoordinates
XMP XMP:City
XMP:State
XMP:CountryCode
XMP:Country
(only if XMP-exif not specified)
XMP:GPSLatitude
XMP:GPSLongitude
XMP-photoshop
XMP-photoshop:City
XMP-photoshop:State
XMP-photoshop:Country
XMP-iptcCore
XMP-iptcCore:CountryCode
XMP-exif
XMP-exif:GPSLatitude
XMP-exif:GPSLongitude
XMP-iptcExt
XMP-iptcExt:LocationShownCity
XMP-iptcExt:LocationShownProvinceState
XMP-iptcExt:LocationShownCountryCode
XMP-iptcExt:LocationShownCountryName
XMP-iptcExt:LocationShownGPSLatitude
XMP-iptcExt:LocationShownGPSLongitude
IPTC
(older IIM spec.)
IPTC:City
IPTC:Province-State
IPTC:Country-PrimaryLocationCode
IPTC:Country-PrimaryLocationName
GPS or EXIF
GPS:GPSLatitude
GPS:GPSLongitude
GPS:GPSLatitudeRef
GPS:GPSLongitudeRef
Keys
Keys:GPSCoordinates
Keys:LocationName (with "City, Region, Country")
ItemList
ItemList:GPSCoordinates
UserData
UserData:GPSCoordinates
QuickTime
(only if Keys, ItemList or UserData not specified)
QuickTime:GPSCoordinates

While geotagging

The special value of "geotag" may be used to represent the GPS coordinates determined while geotagging from a GPS track file. For example:
exiftool -geolocate=geotag -geotag track.gpx c:\images
Regular expressions may be also used when geotagging. For example, to constrain the search to cities within France or Germany:
exiftool -geolocate="geotag,co/France|Germany/" -geotag track.gpx c:\images
Limiting the search like this will result in better performance when geotagging a large number of files, but the overhead is significant so it would degrade performance if geotagging only a small number of files.

Extra Features

Language translations

The exiftool -lang option (API Lang option) applies to the tags generated by the API Geolocation option. Note that this language translation feature is optional, and requires installation of an alternate database. For example, with an alternate database installed:
exiftool -api geolocation=Munich,Germany -lang de
gives this output
Geolocation City                : Muenchen
Geolocation Region              : Bayern
Geolocation Subregion           : Regierungsbezirk Oberbayern
Geolocation Country Code        : DE
Geolocation Country             : Bundesrepublik Deutschland
Geolocation Time Zone           : Europe/Berlin
Geolocation Feature Code        : PPLA
Geolocation Population          : 1300000
Geolocation Position            : 48.1375, 11.5755
Note that the language coverage currently isn't very comprehensive, and may only be used when reading (ie. not when writing the Geolocate tag or in the API Geolocation option setting), but may be extended via user-defined translations (see Customization below).

Optional parameters

Four special API options are used as parameters in the geolocation search for both the API Geolocation option and when writing the Geolocate tag.
API OptionDescription
GeolocMinPop Minimum city population to consider when searching for a city in the database. This is compared with the populations from the database which are stored with 2 significant digits. Cities with populations lower than this are not considered in the search.
GeolocMaxDist When determining geolocation from input GPS coordinates, cities with distances in km greater than this are ignored.
GeolocFeature Comma-separated list of feature codes to include in search, or to exclude if the list starts with a dash (-). Valid feature codes are PPL, PPLA, PPLA2, PPLA3, PPLA4, PPLA5, PPLC, PPLCH, PPLF, PPLG, PPLH, PPLL, PPLQ, PPLR, PPLS, PPLX, STLMT and Other, plus possible user-included codes if an alternate database is used. See here for a description of these codes.
GeolocAltNames Flag to use alternate names if available when search for a city name. Default is 1. See Alternate databases below for more information.

Alternate databases

ExifTool is distributed with a geolocation database of cities with population 2000 or greater (plus adm div down to PPLA2), but a larger database of cities with population 500 or greater and adm div down to PPLA4 may be downloaded from the link below. To use the new database, unzip the downloaded file and add the following line to your ExifTool config file:
$Image::ExifTool::Geolocation::geoDir = '/PATH/TO/Geolocation500';
where /PATH/TO is the name of the directory containing the unzipped Geolocation500 directory. (Note that this may not work in Windows if there are Unicode characters in the path name.) The $geoDir variable may also be set to an empty string to completely disable loading of a Geolocation database, which may be useful for working with only a user-defined database.
A database of alternate city names and language translation files are also included in the zip file. The alternate names are consulted only when a full city name is provided in a search (ie. not using a regular expression), the API GeolocAltNames option is set (which is the default), and the AltNames.dat file is found and matches the number of entries in the currently loaded Geolocation.dat database.
Download database with cities of population 500 or
greater, including alternate names and translations:
(requires ExifTool 12.81 or later)
Geolocation500-20240417.zip (7.3 MB)
A "build_geolocation" utility script is available to allow users to build their own alternate geolocation databases for ExifTool. This utility requires that the necessary input database files from geonames.org have been downloaded, and provides control over the population thresholds and included feature codes on a per-country basis. Read the help documentation or download the utility (requires Perl to run).
For example, the command below generates a database including cities of population 2000 or greater, except 500 or greater in Canada and the U.S., plus all cities with feature class "PPL" regardless of population in Ontario Canada and New York State, with alternate names and translations only for English, French and German:
build_geolocation -p 2000 -p ca,us=500 -c "ca.ontario,us.new york=+PPL" -l en,fr,de DIR
For this command, the necessary geonames database files must exist in the DIR directory, and the output will go to "DIR/Geolocation_out" but the -o option may be used to specify anohter directory (see build_geolocation -h for details). The "+PPL" adds PPL to the list of features to always keep (which is "PPLA,PPLA2" by default).

Listing the database

The exiftool application -listgeo option may be used to list all entries in the Geolocation database, including any user-defined entries (see below for a description of how to create these). For this output, the API GeolocMinPop, GeolocFeature and GeolocAltNames options are in effect, and the application -sort and -lang options may be used to sort the output alphabetically and/or apply a language translation.

Customization

User-defined database entries and language translations may be added through definitions in the ExifTool config file. (Note that the config file must be UTF-8 encoded.)
Database entries are added in this format:
# Add user-defined cities to the Geolocation lookup
@Image::ExifTool::UserDefined::Geolocation = (
    # (city,region,subregion,country_code,country,timezone,feature_code,population,lat,lon)
    ['Sinemorets','Burgas','Obshtina Tsarevo','BG','','Europe/Sofia','PPL',400,42.06115,27.97833],
    ['Silistar','Burgas','Obshtina Tsarevo','BG','','Europe/Sofia','PPL',0,42.02199,28.00959],
    ['Krapets','Dobrich','Obshtina Shabla','BG','','Europe/Sofia','PPL',300,43.62621,28.56669],
);
The region, subregion, timezone and country may be set to empty strings if they are not applicable or not known, but all other fields must be filled. If the country name is empty (as above), then the name from the database is used if available, based on the specified country code. An optional comma-separated list of alternate city names may be added as an additional item after the longitude.
User-defined language translations take this format:
# Add user-defined language translations (note that user-defined
# translations override any preexisting translations)
%Image::ExifTool::Geolocation::geoLang = (
    # translations for the Russian language
    ru => {
        # city, region, subregion and/or country names may be specified
        # alone to provide a translation for any matching name
        'Sinemorets' => 'синеморец',
        'Bulgaria' => 'Болгария',
        # a country code and optional region (joined without a comma) and an
        # optional subregion may be added before the city to be more specific
        'BGBurgas,Obshtina Shabla,Silistar' => 'силистар',
        'BG,Krapets' => 'Крапец',
        # the city is omitted to specify only region, subregion or country name
        'GR,' => 'Греция',          # translate country name only
        'BGBurgas,' => 'Бургас',    # translate region name only
        'BGBurgas,Obshtina Tsarevo,' => 'Муниципалитет Царево',# subregion only
    },
    # (add other languages here)
);
Translations in are organized into sections in the %geoLang hash based on the language code (eg. "ru" in the example above). Within each section are the key/value pairs which are used to apply the translation for that language. The keys on the left are used to match names in the database, translating them to the values on the right. Here is a breakdown of the format of the keys on the left:
Key formatMatches...
Nnnnany city, region, subregion or country with name "Nnnn"
,Nnnnany city with name "Nnnn" in any region or country
CC,Nnnnany city with name "Nnnn" in any region and any subregion of the country with code "CC"
CCRrrr,Nnnnany city with name "Nnnn" in region "Rrrr" and any subregion of the country with code "CC"
CCRrrr,Ssss,Nnnnany city with name "Nnnn" in region "Rrrr" and subregion "Ssss" of the country with code "CC"
CC,the country with code "CC"
CCRrrr,the region "Rrrr" in the country with code "CC"
CCRrrr,Ssss,the subregion "Ssss" in region "Rrrr" of the country with code "CC"
Entries in the table above are ordered from lowest at the top to highest priority at the bottom, with the match of highest priority taking precedence when translating a name.
User-defined language translations may be added for the default 'en' language to affect the returned names when no language is specified.

Created Mar 12, 2024
Last revised Apr 17, 2024

<-- Back to ExifTool home page