ExifTool has the ability to generate geolocation information (including city,region, subregion and country) from GPS coordinates (and visa versa) using anincluded database of all cities with population 2000 or greater basedon a Creative Commons database fromgeonames.org.(An extended version of the ExifTool database is available with cities down to apopulation of 500.See below for more information.) There aretwo basic modes of operation: one to generate geolocation information whenreading from a file, and another to write geolocation information to a file.
Geolocation tags may be generated when reading a file by setting theAPI Geolocation option. For example,exiftool -api geolocation "-geolocation*" test.jpgproduces an output similar to this for a file containing GPS coordinates:Geolocation City : Saint-HyacintheGeolocation Region : QuebecGeolocation Subregion : MontérégieGeolocation Country Code : CAGeolocation Country : CanadaGeolocation Time Zone : America/TorontoGeolocation Feature Code : PPLGeolocation Feature Type : Populated PlaceGeolocation Population : 50000Geolocation Position : 45.6307, -72.9571Geolocation Distance : 1.8 kmGeolocation Bearing : 226The above tags are generated based on either a GPS position (preferentially), orfrom city, state/province and country information. The meanings of theresulting region and subregion tags vary by country. In North America forexample, region corresponds to state or province, and subregion corresponds tocounty. The population is rounded to 2 significant digits, and the distance andbearing are generated only when an input GPS position is provided, and give thedistance in km and the compass bearing from the input GPS point to theGeolocationPosition of the returned city. See theExtra Tags documentation for a brief descriptionof each Geolocation tag.
Default tags
The Geolocation option has a list of default tags that it looks forin the source file to use as inputs for determining the nearest city. These tagsare, 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 thefirst available of these tags are used as inputs to determine the geolocation. If no GPS position is found, the file is checked forcity/state/province/country/countrycode tags in the list, and the inputs aretaken from the first available city information. Note that each specified citytag must come before the corresponding state/province, etc. If multiplematches are found, the city with the largest population is returned unlessthe-a(APIDuplicates)option is used in which case all matching cities are returned.
To override the default list of tags, set the Geolocation optionto a comma-separated list of tags beginning with dollar signs, butnote thatComposite tags may not be used. For example:exiftool -api geolocation="$XMP:GPSLatitude,$XMP:GPSLongitude" test.jpg(Note: On Mac/Linux/PowerShell, use single quotes (') insteadof double quotes (") around arguments containing a dollar sign($).)
Default input
It may be useful to specify a default input for the case where noneof the specified tags are found. For this, the default input is added to theGeolocation setting. For example, the information returned by this commandincludes Geolocation information for the specified coordinates if none of thedefault tags listed above are found:exiftool -api geolocation="44.3414,-72,1234" test.jpgAlternately, default city information may be specified. When doing this, thecity name comes first, and is optionally followed by region (eg. state orprovince), subregion (eg. county), country code and/or country name in anyorder, separated by commas. For example:exiftool -api geolocation="London,England" test.jpgThe default tags may be specified at the same time as the default value tooverride the pre-defined list of default tags, for example:exiftool -api geolocation="$gpslatitude,$gpslatituderef,\ $gpslongitude,$gpslongituderef,-37.81,144.96" test.jpgThis feature may be used to generate geolocation information with no input fileat all. For example, this command:exiftool -api geolocation=Munich,Germanyproduces this output:Geolocation City : MunichGeolocation Region : BavariaGeolocation Subregion : Upper BavariaGeolocation Country Code : DEGeolocation Country : GermanyGeolocation Time Zone : Europe/BerlinGeolocation Feature Code : PPLAGeolocation Feature Type : Seat Of A First-order Administrative DivisionGeolocation Population : 1300000Geolocation Position : 48.1375, 11.5755If both city name and GPS coordinates are provided, the nearest citymatching the specified name(s) is returned, and the result includes thedistance and compass bearing from the specified GPS position to this city.For example:>exiftool -api geolocation=44,-76,KingstonGeolocation City : KingstonGeolocation Region : OntarioGeolocation Subregion : Frontenac CountyGeolocation Country Code : CAGeolocation Country : CanadaGeolocation Time Zone : America/TorontoGeolocation Feature Code : PPLGeolocation Feature Type : Populated PlaceGeolocation Population : 110000Geolocation Position : 44.2298, -76.4810Geolocation Distance : 46.12 kmGeolocation Bearing : 296Multiple nearby cities may be returned instead of just the nearest by addingnum=##to the Geolocation option string, where##is thedesired number of cities. The returned cities are ordered from nearest tofurthest, and distinguished by the family 3 (document number) group which allowsthem to be output as separate lines with the-poption. For example,the nearest cities to a specified GPS position:>exiftool -ee -p geo.fmt -api geolocation=49.48,6.37,num=47.00 km,286 deg,PPLA3,Mondorf-les-Bains,Luxembourg7.24 km,357 deg,PPLA2,Remich,Luxembourg11.55 km,80 deg,PPL,Orscholz,Germany12.32 km,240 deg,PPL,Cattenom,Franceor the nearest cities to a specified city:>exiftool -ee -p geo.fmt -api geolocation="new york city,num=5"0.00 km,0 deg,PPL,New York City,United States0.31 km,287 deg,PPL,Tribeca,United States0.74 km,203 deg,PPLX,Financial District,United States0.85 km,77 deg,PPLX,Chinatown,United States0.92 km,255 deg,PPL,Battery Park City,United StatesNote that the-eeoption must be used for the-poption to iterate through the returned cities since they are returned assub-documents. Here is the "geo.fmt" file used in the above commands:$geolocationdistance,$geolocationbearing deg,$geolocationfeaturecode,$geolocationcity,$geolocationcountryOr for a JSON-format output, a command like this may be useful:exiftool -j -g3 -api geolocation=49.48,6.37,num=4
Regular expressions
An advanced feature allows standard Perl regular expressions of theform/expr/to be used to match city, region, etc names. Theregular expression may be prefixed by "ci", "re","sr", "cc" or "co" to apply only to City,Region, Subregion, CountryCode or Country names, otherwise the expressionmatches any of these. A dash at the start is used to exclude matching entries(eg.-co/Canada/excludes cities in Canada from the search). Theregular expression matches are case sensitive unless "i" isadded 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 namesexiftool -api geolocation=sr/frontenac/i# and this matches the city "Kingston" with "Ontario" in any other fieldexiftool -api geolocation=kingston,/ontario/iOne more feature allows both GPS and place names to be used together if no inputtags are found and the default value includes both of these. In this case theclosest city matching all of the specified names is returned. For example, tofind 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 ofa country and want to keep the geolocated cities within that country.
†Currently case insensitivity applies only to ASCII characters.
A write-onlyGeolocate tag isprovided as a convenience to simplify the writing of standard geolocation tags.This is an alternative to using the APIGeolocationoption and copying the generated Geolocation tags individually to the desiredlocations, and is completely independent of the API Geolocation setting(although theoptional parameters still apply).
Writing the Geolocate tag with GPS coordinates generates city,state/province, country code and country tags. By default, XMP tags aregenerated (plus Keys:LocationName for videos), but group name(s) may bespecified to write tags to other locations (see table below). For example, towrite the XMP City, State, CountryCode and Country tags from specified GPScoordinates: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 cityname. A region, subregion, country code and/or country name may be added in anyorder after the city name, separated by commas. Fields must match exactly theentries in the database, but case is not significant†. Regular expressions mayalso be used in the same format as for the API Geolocation option(see above). If more than one matching city is found then aminor warning is issued and the tags are not written, but the IgnoreMinorErrorsoption may be used to write tags for the matching city with the largestpopulation. For example, the following command writes XMP:GPSLatitude, etc andIPTC:City, etc for Paris France.exiftool -xmp:iptc:geolocate="paris,fr" test.jpgThe table below lists the tags that are written for each group name specifiedfor the Geolocate tag. Multiple group names may be used. In some cases,different tags are written based on whether input GPS coordinates or a city namewere used. As mentioned, the Geolocate tag is for convenience only, and makesit easier to write common tags listed in the table below. The APIGeolocation option is more flexible andmay be used with the-tagsFromFileoption to write any combinationof tags, but the command may be more complicated.
Group Name(s) Specified Tags Written based on input... GPS coordinates City name (none) XMP:City
XMP:State
XMP:CountryCode
XMP:Country
Keys:LocationNameGPSLatitude
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:State
XMP-photoshop:CountryXMP-iptcCore XMP-exif
XMP-exif:GPSLongitudeXMP-iptcExt
XMP-iptcExt:LocationShownProvinceState
XMP-iptcExt:LocationShownCountryCode
XMP-iptcExt:LocationShownCountryName
XMP-iptcExt:LocationShownGPSLatitude
XMP-iptcExt:LocationShownGPSLongitudeIPTC
(older IIM spec.)
IPTC:Province-State
IPTC:Country-PrimaryLocationCode
IPTC:Country-PrimaryLocationNameGPS or EXIF
GPS:GPSLongitude
GPS:GPSLatitudeRef
GPS:GPSLongitudeRefKeys Keys:LocationName
(with "City, Region, Country")Keys:GPSCoordinates ItemList UserData QuickTime
QuickTime:GPSCoordinates
While geotagging
The special value of "geotag" may be used to represent the GPScoordinates determined whilegeotagging from a GPStrack file. For example:exiftool -geolocate=geotag -geotag track.gpx c:\imagesRegular expressions may be also used when geotagging. For example, to constrainthe search to cities within France or Germany:exiftool -geolocate="geotag,co/France|Germany/" -geotag track.gpx c:\imagesLimiting the search like this will result in better performance when geotagginga large number of files, but the overhead is significant so it would degradeperformance if geotagging only a small number of files.
Language translations
The exiftool-langoption (APILangoption) applies to the tags generated by the APIGeolocation option.Note that this language translation feature is optional, and requiresinstallation of analternate database. For example,with an alternate database installed:exiftool -api geolocation=Munich,Germany -lang degives this outputGeolocation City : MuenchenGeolocation Region : BayernGeolocation Subregion : Regierungsbezirk OberbayernGeolocation Country Code : DEGeolocation Country : Bundesrepublik DeutschlandGeolocation Time Zone : Europe/BerlinGeolocation Feature Code : PPLAGeolocation Feature Type : Seat Of A First-order Administrative DivisionGeolocation Population : 1300000Geolocation Position : 48.1375, 11.5755Note that the language coverage currently isn't very comprehensive, and may onlybe used when reading (ie. not when writing the Geolocate tag or in the APIGeolocation option setting), but may beextended via user-defined translations (seeCustomizationbelow).
Optional parameters
Four special API options are used as parameters in the geolocationsearch 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 thedatabase. This is compared with the populations from the database which arestored with 2 significant digits. Cities with populations lower than this arenot considered in the search. GeolocMaxDist When determining geolocation from input GPS coordinates, cities withdistances in km greater than this are ignored. GeolocFeature Comma-separated list of feature codes to include in search, or to excludeif 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,PPLW, PPLX, STLMT and Other, plus possible user-included codes if an alternatedatabase is used. Seeherefor a description of these codes. GeolocAltNames Flag to use alternate names if available when search for a cityname. Default is 1. SeeAlternate databases belowfor more information.
Alternate databases
ExifTool is distributed with a geolocation database of citieswith population 2000 or greater (plus adm div down toPPLA2), but a largerdatabase of cities with population 500 or greater and adm div down toPPLA4 may be downloadedfrom the link below. This database also includes alternate city names andlanguage translations. To use the new database, unzip the downloaded file and addthe following line to yourExifTool config file:$Image::ExifTool::Geolocation::geoDir = '/PATH/TO/Geolocation500';where/PATH/TOis the name of the directory containing the unzippedGeolocation500 directory.(Note that this may not work in Windows if thereare Unicode characters in the path name.) The$geoDirvariablemay also be set to an empty string to completely disable loading of aGeolocation database, which may be useful for working with only a user-defineddatabase. As a convenience,$geoDirmay be set at runtime via theAPIGeoDir pseudo-option.
A database of alternate city names and language translation files arealso included in the zip file. The alternate names are consulted only when a fullcity name is provided in a search (ie. not using a regular expression), the APIGeolocAltNames option is set (which isthe default), and the AltNames.dat file is found and matches the number ofentries in the currently loaded Geolocation.dat database. For example, searchingfor "Big Apple" with the alternate names enabled would return the information forNew York City.
Download database with cities of population 500 or
greater, including alternate names and translations:
(requires ExifTool 12.82 or later)Geolocation500-20250522.zip (7.7 MB)
A "build_geolocation" utility script is available to allow usersto build their own alternate geolocation databases for ExifTool. This utilityrequires that the necessary input database files fromgeonames.org have beendownloaded, and provides control over the population thresholds and includedfeature codes on a per-country basis.Read the help documentation ordownload the utility(requires Perl to run).
For example, the command below generates a database including citiesof 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 OntarioCanada and New York State, with alternate names and translations only forEnglish, French and German:build_geolocation -p 2000 -p ca,us=500 -c "ca.ontario,us.new york=+PPL" -l en,fr,de DIRFor this command, the necessary geonames database files must exist in theDIRdirectory, and the output will go to"DIR/Geolocation_out" but the-ooption may be used to specifyanother directory (seebuild_geolocation -hfor details). The"+PPL" adds PPL to the list of features to always keep (which is"PPLA,PPLA2" by default). Any feature type(s) from the geonames databasemay be added -- this isn't restricted to just cities.
Listing the database
The exiftool application-listgeooption may be used tolist 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 APIGeolocMinPop,GeolocFeature andGeolocAltNames options are in effect, and the application-sortand-langoptions may be used tosort the output alphabetically and/or apply a language translation.
Customization
User-defined database entries and language translations may be addedthrough definitions in theExifTool config file. (Notethat 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 city name, country_code, population and latitude/longitude fields must befilled, but all other fields may be left empty if they are not applicable or notknown. If the country name is empty (as above), then the name from the databaseis used if available, based on the specified country code. An optionalcomma-separated list of alternate city names may be added as an additional itemafter 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%geoLanghashbased on the language code (eg. "ru" in the example above). Withineach section are the key/value pairs which are used to apply the translation forthat 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 formatof the keys on the left:Entries in the table above are ordered from lowest priority at the top tohighest at the bottom, with the match of highest priority taking precedence whentranslating 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" 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"
User-defined language translations may be added for the default 'en'language to affect the returned names when no language is specified.
1."ExifTool returns an unexpected city for the specified GPS coordinates"
First, try listing a number of nearby cities to see if ExifTool isjust finding something closer. For example the following command lists the10 cities nearest to a specified GPS position, where "LAT" and "LON" are signedfloating-point latitude and longitude:exiftool -api geolocation=LAT,LON,num=10 -a -g3If the expected city is in this list, take note of the feature codes and populationsof these cities. The APIGeolocFeatureand APIGeolocMinPop options may be usedto limit the feature types and/or population of the returned cities accordingto your requirements. For example, to avoid returning PPLX city types and citieswith population less than 10000, you could do this:exiftool -api geolocfeature=-PPLX -api geolocminpop=10000 ...However, if your city doesn't appear in the list, then it is likely that itdoesn't exist in the ExifTool Geolocation database. You can check this bysearching for the specific city in the ExifTool database. This command returnsall cities with name "CITYNAME" exactly (case insensitive):exiftool -api geolocation="CITYNAME" -m -a -g3or this command may be used to match cities with "STRING" anywhere in their name(the added "i" makes the match case insensitive):exiftool -api geolocation="ci/STRING/i" -m -a -g3A city may not appear in the ExifTool Geolocation database if the populationis lower than a minimum, which is 2000 for the standard database. Analternate database is available with cities down to population500, but it may be a good idea to first see if the city exists in the sourcegeonames.org database. Use the search fieldhereto see if the city does exist and to determine its population and feature codes(click on the appropriate city in the list returned by the search).
If the city doesn't exist at geonames.org or has incorrect information,there are two things you can do: 1. Create an account and geonames.org and updatetheir database with the correct information. This information will eventuallypropagate down to ExifTool (probably within a few months), or you can build yourownalternate database. Or 2. Create auser-defined entry for your city in the ExifTool config file.
<-- Back to ExifTool home page