Reading Geolocation
Writing Geolocation
Extra Features
  - Language translations
  - Optional parameters
  - Alternate database
  - 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 including cities down to a population of 500. See Extra Features 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:
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 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, region, subregion and country information. The meanings of the 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.
The Geolocation option has a list of default tags that it looks for in the source file to use as inputs for determining the geolocation. 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 highest 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. For example:
exiftool -api geolocation='$XMP:GPSLatitude,$XMP:GPSLongitude' test.jpg
(Note: use double quotes instead of single quotes in Windows CMD shells.)
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:
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 Population          : 1300000
Geolocation Position            : 48.1375, 11.5755
An advanced feature allows 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. The 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

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.
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 as described in the previous section. 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 greatest 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
Additionally, the Geolocate tag may be set to the value "geotag" to generate the geolocation tags from GPS coordinates when geotagging. For example:
exiftool -geolocate=geotag -geotag track.gpx c:\images
The table below lists the tags that are written based on the group name(s) specified for the Geolocate tag.
Group Name(s) SpecifiedTags Written based on input...
GPS coordinatesCity name
(none) XMP:City
XMP:State
XMP:CountryCode
XMP:Country
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
ItemList
ItemList:GPSCoordinates
UserData
UserData:GPSCoordinates
QuickTime
(only if Keys, ItemList or UserData not specified)
QuickTime:GPSCoordinates

Extra Features

Language translations

The exiftool -lang option (API Lang option) applies to the tags generated by the API Geolocation option. For example,
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 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

Two 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.

Alternate database

ExifTool is distributed with a geolocation database of cities with population 2000 or greater (including 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 here: Geolocation500.zip (3.2 MB). 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. 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.

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 GeoMinPop option is 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,population,lat,lon)
    ['Sinemorets','Burgas','Obshtina Tsarevo','BG','','Europe/Sofia',400,42.06115,27.97833],
    ['Silistar','Burgas','Obshtina Tsarevo','BG','','Europe/Sofia',0,42.02199,28.00959],
    ['Krapets','Dobrich','Obshtina Shabla','BG','','Europe/Sofia',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.
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"
CCRrrr,Ssss,the subregion "Ssss" in region "Rrrr" of the country with code "CC"
CCRrrr,the region "Rrrr" in the country with code "CC"
CC,the country with code "CC"
Entries in the table above are ordered from lowest to highest priority, with the match of highest priority taking precedence when translating a name.

Created Mar 12, 2024
Last revised Mar 15, 2024

<-- Back to ExifTool home page