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.
Geolocation tags may be generated when reading a file by setting the API Geolocation option. For example,exiftool -api geolocation "-geolocation*" test.jpgproduces 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.9571The 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, LocationShownCountryNameFirst, 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.jpgAlternately, default city information may be specified:exiftool -api geolocation="London,England" test.jpgThe 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.jpgThis feature may be used to generate geolocation information with no input file at all. For example, this command:exiftool -api geolocation=Munich,Germanyproduces 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.5755An 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
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.jpgor to write the IPTC tags from GPS coordinates in a file:exiftool "-iptc:geolocate<gpsposition" test.jpgConversely, 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.jpgAdditionally, 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:\imagesThe table below lists the tags that are written based on the group name(s) specified for the Geolocate tag.
Group Name(s) Specified Tags Written based on input... GPS coordinates City name (none) XMP:City
XMP:State
XMP:CountryCode
XMP:CountryGPSLatitude
GPSLongitude
GPSLatitudeRef
GPSLongitudeRef
QuickTime::GPSCoordinatesXMP XMP:City
XMP:State
XMP:CountryCode
XMP:Country(only if XMP-exif not specified)
XMP:GPSLatitude
XMP:GPSLongitudeXMP-photoshop XMP-photoshop:City
XMP-photoshop:State
XMP-photoshop:CountryXMP-iptcCore XMP-iptcCore:CountryCodeXMP-exif XMP-exif:GPSLatitude
XMP-exif:GPSLongitudeXMP-iptcExt XMP-iptcExt:LocationShownCity
XMP-iptcExt:LocationShownProvinceState
XMP-iptcExt:LocationShownCountryCode
XMP-iptcExt:LocationShownCountryName
XMP-iptcExt:LocationShownGPSLatitude
XMP-iptcExt:LocationShownGPSLongitudeIPTC
(older IIM spec.) IPTC:City
IPTC:Province-State
IPTC:Country-PrimaryLocationCode
IPTC:Country-PrimaryLocationNameGPS or EXIF GPS:GPSLatitude
GPS:GPSLongitude
GPS:GPSLatitudeRef
GPS:GPSLongitudeRefKeys Keys:GPSCoordinatesItemList ItemList:GPSCoordinatesUserData UserData:GPSCoordinatesQuickTime (only if Keys, ItemList or UserData not specified)
QuickTime:GPSCoordinates
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 degives this outputGeolocation 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.5755Note 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 Option Description 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:Entries in the table above are ordered from lowest to highest priority, with the match of highest priority taking precedence when translating a name.
Key format Matches... Nnnn any city, region, subregion or country with name "Nnnn" ,Nnnn any city with name "Nnnn" in any region or country CC,,Nnnn any city with name "Nnnn" in any region and any subregion of the country with code "CC" CCRrrr,,Nnnn any city with name "Nnnn" in region "Rrrr" and any subregion of the country with code "CC" CCRrrr,Ssss,Nnnn any 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"