File: geolocation.html

package info (click to toggle)
libimage-exiftool-perl 13.25%2Bdfsg-1
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 32,600 kB
sloc: perl: 297,808; xml: 123; makefile: 22; sh: 15
file content (636 lines) | stat: -rw-r--r-- 31,758 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
  <title>ExifTool Geolocation Feature</title>
<link rel=stylesheet type='text/css' href='style.css' title='Style'>
<style type="text/css">
<!--
pre   { color: #800; margin-left: 4em }
.indent { margin-left: 22% }
table.dl        { border: 1px solid gray; border-collapse: collapse }
table.dl td     { padding: .4em .8em }
i.sm  { font-size: 12pt }
-->
</style>
</head>
<body>
<div class='index'>
<a href="#Read">Reading Geolocation</a>
<br>&nbsp; - <a href="#DefTags">Default tags</a>
<br>&nbsp; - <a href="#DefInput">Default input</a>
<br>&nbsp; - <a href="#Reg">Regular expressions</a>
<br><a href="#Write">Writing Geolocation</a>
<br>&nbsp; - <a href="#Geotag">While geotagging</a>
<br><a href="#Extra">Extra Features</a>
<br>&nbsp; - <a href="#Lang">Language translations</a>
<br>&nbsp; - <a href="#Params">Optional parameters</a>
<br>&nbsp; - <a href="#Alt">Alternate databases</a>
<br>&nbsp; - <a href="#List">Listing the database</a>
<br>&nbsp; - <a href="#Custom">Customization</a>
<br><a href="#Troubleshooting">Troubleshooting</a>
</div>
<a name="Geolocation"></a>
<h1>ExifTool Geolocation Feature
<i class='sm lt'>(aka "Reverse Geocoding")</i></h1>

<p>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 <a href="http://www.geonames.org/export/">geonames.org</a>.
(An extended version of the ExifTool database is available with cities down to a
population of 500. <a href="#Alt">See below</a> 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.</p>

<a name="Read"></a>
<h3>Reading Geolocation Information</h3>

<blockquote>Geolocation tags may be generated when reading a file by setting the
<a href="ExifTool.html#Geolocation">API Geolocation option</a>.  For example,

<pre>exiftool -api geolocation "-geolocation*" test.jpg</pre>

produces an output similar to this for a file containing GPS coordinates:

<pre class=blk>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 Feature Type        : Populated Place
Geolocation Population          : 50000
Geolocation Position            : 45.6307, -72.9571
Geolocation Distance            : 1.8 km
Geolocation Bearing             : 226</pre>

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
<a href="TagNames/Extra.html">Extra Tags documentation</a> for a brief description
of each Geolocation tag.</blockquote>

<a name="DefTags"></a>
<p><b>Default tags</b></p>

<blockquote>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:

<blockquote>GPSLatitude, GPSLongitude, GPSLatitudeRef, GPSLongitudeRef,
GPSCoordinates, LocationShownGPSLatitude, LocationShownGPSLongitude,
XMP:City, State, CountryCode, Country,
IPTC:City, Province-State, Country-PrimaryLocationCode, Country-PrimaryLocationName,
LocationShownCity, LocationShownProvinceState, LocationShownCountryCode,
LocationShownCountryName</blockquote>

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 <code>-a</code> (API <a href="ExifTool.html#Duplicates">Duplicates</a>)
option is used in which case all matching cities are returned.</blockquote>

<blockquote>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:

<pre>exiftool -api geolocation="$XMP:GPSLatitude,$XMP:GPSLongitude" test.jpg</pre>

<i>(Note: On Mac/Linux/PowerShell, use single quotes (<code>'</code>) instead
of double quotes (<code>"</code>) around arguments containing a dollar sign
(<code>$</code>).)</i></blockquote>

<a name="DefInput"></a>
<p><b>Default input</b></p>

<blockquote>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:

<pre>exiftool -api geolocation="44.3414,-72,1234" test.jpg</pre>

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:

<pre>exiftool -api geolocation="London,England" test.jpg</pre>

The default tags may be specified at the same time as the default value, for example:

<pre>exiftool -api geolocation="$gpslatitude,$gpslongitude,-37.81,144.96" test.jpg</pre>

This feature may be used to generate geolocation information with no input file
at all.  For example, this command:

<pre>exiftool -api geolocation=Munich,Germany</pre>

produces this output:

<pre class=blk>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 Feature Type        : Seat Of A First-order Administrative Division
Geolocation Population          : 1300000
Geolocation Position            : 48.1375, 11.5755</pre>

If both city name and GPS coordinates are provided, the nearest city
matching the specified name(s) is returned, and the result includes the
distance and compass bearing from the specified GPS position to this city.
For example:

<pre class=blk>> <span class=code>exiftool -api geolocation=44,-76,Kingston</span>
Geolocation City                : Kingston
Geolocation Region              : Ontario
Geolocation Subregion           : Frontenac County
Geolocation Country Code        : CA
Geolocation Country             : Canada
Geolocation Time Zone           : America/Toronto
Geolocation Feature Code        : PPL
Geolocation Feature Type        : Populated Place
Geolocation Population          : 110000
Geolocation Position            : 44.2298, -76.4810
Geolocation Distance            : 46.12 km
Geolocation Bearing             : 296</pre>

Multiple nearby cities may be returned instead of just the nearest by adding
<code>num=##</code> to the Geolocation option string, where <code>##</code> is the
desired number of cities.  The returned cities are ordered from nearest to
furthest, and distinguished by the family 3 (document number) group which allows
them to be output as separate lines with the <code>-p</code> option.  For example,
the nearest cities to a specified GPS position:

<pre class=blk>> <span class=code>exiftool -ee -p geo.fmt -api geolocation=49.48,6.37,num=4</span>
7.00 km,286 deg,PPLA3,Mondorf-les-Bains,Luxembourg
7.24 km,357 deg,PPLA2,Remich,Luxembourg
11.55 km,80 deg,PPL,Orscholz,Germany
12.32 km,240 deg,PPL,Cattenom,France</pre>

or the nearest cities to a specified city:

<pre class=blk>> <span class=code>exiftool -ee -p geo.fmt -api geolocation="new york city,num=5"</span>
0.00 km,0 deg,PPL,New York City,United States
0.31 km,287 deg,PPL,Tribeca,United States
0.74 km,203 deg,PPLX,Financial District,United States
0.85 km,77 deg,PPLX,Chinatown,United States
0.92 km,255 deg,PPL,Battery Park City,United States</pre>

Note that the <code>-ee</code> option must be used for the <code>-p</code>
option to iterate through the returned cities since they are returned as
sub-documents.  Here is the "geo.fmt" file used in the above commands:

<pre>$geolocationdistance,$geolocationbearing deg,$geolocationfeaturecode,$geolocationcity,$geolocationcountry</pre>

Or for a JSON-format output, a command like this may be useful:

<pre class=blk><span class=code>exiftool -j -g3 -api geolocation=49.48,6.37,num=4</span></pre>
</blockquote>

<a name="Reg"></a>
<p><b>Regular expressions</b></p>

<blockquote>An advanced feature allows standard Perl regular expressions of the
form <code>/expr/</code> to be used to match city, region, etc names. The
regular expression may be prefixed by "<code>ci</code>", "<code>re</code>",
"<code>sr</code>", "<code>cc</code>" or "<code>co</code>" 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. <code>-co/Canada/</code> excludes cities in Canada from the search).  The
<b>regular expression matches are case sensitive</b> unless "<code>i</code>" is
added after the expression.  For example:

<pre><span class=blk># this matches "Frontenac" in any place name (case insensitive<sup>&dagger;</sup>)</span>
exiftool -api geolocation=/frontenac/i

<span class=blk># while this matches "Frontenac" only in subregion names</span>
exiftool -api geolocation=sr/frontenac/i

<span class=blk># and this matches the city "Kingston" with "Ontario" in any other field</span>
exiftool -api geolocation=kingston,/ontario/i</pre>

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:

<pre>exiftool -api geolocation="40.784,-73.966,co/Canada/"</pre>

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.</blockquote>

<blockquote><sup>&dagger;</sup> <i>Currently case insensitivity applies only to ASCII characters.</i></blockquote>

<hr>
<a name="Write"></a>
<h3>Writing Geolocation Information</h3>

<blockquote>A write-only <a href="TagNames/Extra.html">Geolocate tag</a> is
provided as a convenience to simplify the writing of standard geolocation tags.
This is an alternative to using the API <a href="ExifTool.html#Geolocation">Geolocation</a>
option and copying the generated Geolocation tags individually to the desired
locations, and is completely independent of the API Geolocation setting
(although the <a href="#Params">optional parameters</a> still apply).</blockquote>

<blockquote>Writing the Geolocate tag with GPS coordinates generates city,
state/province, country code and country tags.  By default, XMP tags are
generated (plus Keys:LocationName for videos), 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:

<pre>exiftool "-geolocate=45.6429,-72.9374" test.jpg</pre>

or to write the IPTC tags from GPS coordinates in a file:

<pre>exiftool "-iptc:geolocate&lt;gpsposition" test.jpg</pre>

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<sup>&dagger;</sup>.  Regular expressions may
also be used in the same format as for the API Geolocation option
(<a href="#Reg">see above</a>).  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.

<pre>exiftool -xmp:iptc:geolocate="paris,fr" test.jpg</pre>

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 input GPS coordinates or a city name
were used.  As mentioned, the Geolocate tag is for convenience only, and makes
it easier to write common tags listed in the table below.  The API
<a href="ExifTool.html#Geolocation">Geolocation</a> option is more flexible and
may be used with the <code>-tagsFromFile</code> option to write any combination
of tags, but the command may be more complicated.

<blockquote><table width='90%' class='norm'>
<tr><th rowspan='2'>Group Name(s) Specified</th><th colspan='2'>Tags Written based on input...</th></tr>
<tr><th width='35%'>GPS coordinates</th><th width='35%'>City name</th></tr>
<tr><td align='center'><i>(none)</i></td><td>
    XMP:City<br>
    XMP:State<br>
    XMP:CountryCode<br>
    XMP:Country<br>
    Keys:LocationName</td><td>
    GPSLatitude<br>
    GPSLongitude<br>
    GPSLatitudeRef<br>
    GPSLongitudeRef<br>
    QuickTime::GPSCoordinates</td></tr>
<tr><td align='center'>XMP</td><td>
    XMP:City<br>
    XMP:State<br>
    XMP:CountryCode<br>
    XMP:Country</td><td>
    <i>(only if XMP-exif not specified)</i><br>
    XMP:GPSLatitude<br>
    XMP:GPSLongitude</td></tr>
<tr><td align='center'>XMP-photoshop</td><td colspan='2'><div class='indent'>
    XMP-photoshop:City<br>
    XMP-photoshop:State<br>
    XMP-photoshop:Country</div></td></tr>
<tr><td align='center'>XMP-iptcCore</td><td colspan='2'><div class='indent'>
    XMP-iptcCore:CountryCode</div></td></tr>
<tr><td align='center'>XMP-exif</td><td colspan='2'><div class='indent'>
    XMP-exif:GPSLatitude<br>
    XMP-exif:GPSLongitude</div></td></tr>
<tr><td align='center'>XMP-iptcExt</td><td colspan='2'><div class='indent'>
    XMP-iptcExt:LocationShownCity<br>
    XMP-iptcExt:LocationShownProvinceState<br>
    XMP-iptcExt:LocationShownCountryCode<br>
    XMP-iptcExt:LocationShownCountryName<br>
    XMP-iptcExt:LocationShownGPSLatitude<br>
    XMP-iptcExt:LocationShownGPSLongitude</div></td></tr>
<tr><td align='center'>IPTC<br><i>(older IIM spec.)</i></td><td colspan='2'><div class='indent'>
    IPTC:City<br>
    IPTC:Province-State<br>
    IPTC:Country-PrimaryLocationCode<br>
    IPTC:Country-PrimaryLocationName</div></td></tr>
<tr><td align='center'>GPS or EXIF</td><td colspan='2'><div class='indent'>
    GPS:GPSLatitude<br>
    GPS:GPSLongitude<br>
    GPS:GPSLatitudeRef<br>
    GPS:GPSLongitudeRef</div></td></tr>
<tr><td align='center'>Keys</td>
    <td>Keys:LocationName<br>(with "City, Region, Country")</td>
    <td>Keys:GPSCoordinates</td></tr>
<tr><td align='center'>ItemList</td><td colspan='2'><div class='indent'>
    ItemList:GPSCoordinates</div></td></tr>
<tr><td align='center'>UserData</td><td colspan='2'><div class='indent'>
    UserData:GPSCoordinates</div></td></tr>
<tr><td align='center'>QuickTime</td><td colspan='2'><div class='indent'>
    <i>(only if not written to Keys, ItemList or UserData)</i><br>
    QuickTime:GPSCoordinates</div></td></tr>
</table></blockquote></blockquote>

<a name="Geotag"></a>
<p><b>While geotagging</b></p>

<blockquote>The special value of "geotag" may be used to represent the GPS
coordinates determined while <a href="geotag.html">geotagging</a> from a GPS
track file. For example:

<pre>exiftool -geolocate=geotag -geotag track.gpx c:\images</pre>

Regular expressions may be also used when geotagging.  For example, to constrain
the search to cities within France or Germany:

<pre>exiftool -geolocate="geotag,co/France|Germany/" -geotag track.gpx c:\images</pre>

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.</blockquote>

<hr>
<a name="Extra"></a>
<h3>Extra Features</h3>

<a name="Lang"></a>
<p><b>Language translations</b></p>

<blockquote>The exiftool <code>-lang</code> option (API <a href="ExifTool.html#Lang">Lang</a>
option) applies to the tags generated by the API
<a href="ExifTool.html#Geolocation">Geolocation</a> option.  
<b>Note that this language translation feature is optional</b>, and requires
installation of an <a href="#Alt">alternate database</a>.  For example,
with an alternate database installed:

<pre>exiftool -api geolocation=Munich,Germany -lang de</pre>

gives this output

<pre class=blk>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 Feature Type        : Seat Of A First-order Administrative Division
Geolocation Population          : 1300000
Geolocation Position            : 48.1375, 11.5755</pre>

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
<a href="ExifTool.html#Geolocation">Geolocation</a> option setting), but may be
extended via user-defined translations (see <a href="#Custom">Customization</a>
below).</blockquote>

<a name="Params"></a>
<p><b>Optional parameters</b></p>

<blockquote>Four special API options are used as parameters in the geolocation
search for both the API Geolocation option and when writing the Geolocate tag.

<blockquote>
<table class='norm'>
<tr><th>API Option</th><th>Description</th></tr>
<tr><td><a href="ExifTool.html#GeolocMinPop">GeolocMinPop</a></td>
<td>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.</td></tr>
<tr><td><a href="ExifTool.html#GeolocMaxDist">GeolocMaxDist</a></td>
<td>When determining geolocation from input GPS coordinates, cities with
distances in km greater than this are ignored.</td></tr>
<tr><td><a href="ExifTool.html#GeolocFeature">GeolocFeature</a></td>
<td>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,
PPLW, PPLX, STLMT and Other, plus possible user-included codes if an alternate
database is used.  See <a href="http://www.geonames.org/export/codes.html#P">here</a>
for a description of these codes.</td></tr>
<tr><td><a href="ExifTool.html#GeolocAltNames">GeolocAltNames</a></td>
<td>Flag to use alternate names if available when search for a city
name.  Default is 1.  See <a href="#Alt">Alternate databases</a> below
for more information.</td></tr>
</table></blockquote></blockquote>

<a name="Alt"></a>
<p><b>Alternate databases</b></p>

<blockquote>ExifTool is distributed with a geolocation database of cities
with population 2000 or greater (plus adm div down to
<a href="http://www.geonames.org/export/codes.html#P">PPLA2</a>), but a larger
database of cities with population 500 or greater and adm div down to
<a href="http://www.geonames.org/export/codes.html#P">PPLA4</a> may be downloaded
from the link below.  To use the new database, unzip the downloaded file and add
the following line to your <a href="config.html">ExifTool config file</a>:

<pre>$Image::ExifTool::Geolocation::geoDir = '/PATH/TO/Geolocation500';</pre>

where <code>/PATH/TO</code> is the name of the directory containing the unzipped
Geolocation500 directory.  <i>(Note that this may not work in Windows if there
are Unicode characters in the path name.)</i>  The <code>$geoDir</code> 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.  As a convenience, <code>$geoDir</code> may be set at runtime via the
API <a href="ExifTool.html#GeoDir">GeoDir</a> pseudo-option.</blockquote>

<blockquote>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
<a href="ExifTool.html#GeolocAltNames">GeolocAltNames</a> 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.  For example, searching
for "Big Apple" with the alternate names enabled would return the information for
New York City.

<blockquote><table class='dl'>
<tr><td>Download database with cities of population 500 or<br>
greater, including alternate names and translations:<br>
(requires ExifTool 12.82 or later)</td>
<!-- NOTE: geo.txt on the web site is automatically updated by the publish script from this file name -->
<td><a href="https://exiftool.org/Geolocation500-20250311.zip">Geolocation500-20250311.zip</a> (15 MB)</td></tr>
</table></blockquote></blockquote>

<blockquote>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
<a href="https://download.geonames.org/export/dump/">geonames.org</a> have been
downloaded, and provides control over the population thresholds and included
feature codes on a per-country basis.
<a href="build_geolocation.txt">Read the help documentation</a> or
<a href="https://exiftool.org/build_geolocation.zip">download the utility</a>
(requires Perl to run).</blockquote>

<blockquote>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:

<pre>build_geolocation -p 2000 -p ca,us=500 -c "ca.ontario,us.new york=+PPL" -l en,fr,de DIR</pre>

For this command, the necessary geonames database files must exist in the
<code>DIR</code> directory, and the output will go to
"DIR/Geolocation_out" but the <code>-o</code> option may be used to specify
another directory (see <code>build_geolocation -h</code> for details). The
"<code>+PPL</code>" adds PPL to the list of features to always keep (which is
"PPLA,PPLA2" by default).  Any feature type(s) from the geonames database
may be added -- this isn't restricted to just cities.</blockquote>

<a name="List"></a>
<p><b>Listing the database</b></p>

<blockquote>The exiftool application <code>-listgeo</code> 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
<a href="ExifTool.html#GeolocMinPop">GeolocMinPop</a>,
<a href="ExifTool.html#GeolocFeature">GeolocFeature</a> and
<a href="ExifTool.html#GeolocAltNames">GeolocAltNames</a> options are in effect, and 
the application <code>-sort</code> and <code>-lang</code> options may be used to
sort the output alphabetically and/or apply a language translation.</blockquote>

<a name="Custom"></a>
<p><b>Customization</b></p>

<blockquote>User-defined database entries and language translations may be added
through definitions in the <a href="config.html">ExifTool config file</a>. (Note
that the config file must be UTF-8 encoded.)</blockquote>

<blockquote>Database entries are added in this format:

<pre>
<span class=blk># Add user-defined cities to the Geolocation lookup</span>
@Image::ExifTool::UserDefined::Geolocation = (
    <span class=blk># (city,region,subregion,country_code,country,timezone,feature_code,population,lat,lon)</span>
    ['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],
);</pre>

The city name, country_code, population and latitude/longitude fields must be
filled, but all other fields may be left empty if they are not applicable or not
known.  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.</blockquote>

<blockquote>User-defined language translations take this format:

<pre><span class=blk># Add user-defined language translations (note that user-defined
# translations override any preexisting translations)</span>
%Image::ExifTool::Geolocation::geoLang = (
    <span class=blk># translations for the Russian language</span>
    ru => {
        <span class=blk># city, region, subregion and/or country names may be specified
        # alone to provide a translation for any matching name</span>
        'Sinemorets' =&gt; 'синеморец',
        'Bulgaria' =&gt; 'Болгария',
        <span class=blk># a country code and optional region (joined without a comma) and an
        # optional subregion may be added before the city to be more specific</span>
        'BGBurgas,Obshtina Shabla,Silistar' =&gt; 'силистар',
        'BG,Krapets' =&gt; 'Крапец',
        <span class=blk># the city is omitted to specify only region, subregion or country name</span>
        'GR,' => 'Греция',          <span class=blk># translate country name only</span>
        'BGBurgas,' => 'Бургас',    <span class=blk># translate region name only</span>
        'BGBurgas,Obshtina Tsarevo,' => 'Муниципалитет Царево',<span class=blk># subregion only</span>
    },
    <span class=blk># (add other languages here)</span>
);
</pre>

Translations in are organized into sections in the <code>%geoLang</code> hash
based on the language code (eg. "<code>ru</code>" 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:

<blockquote><table class='norm'><tr><th>Key format</th><th>Matches...</th></tr>
<tr><td>Nnnn</td><td>any city, region, subregion or country with name "Nnnn"</td></tr>
<tr><td>,Nnnn</td><td>any city with name "Nnnn" in any region or country</td></tr>
<tr><td>CC,Nnnn</td><td>any city with name "Nnnn" in any region and any subregion of the country with code "CC"</td></tr>
<tr><td>CCRrrr,Nnnn</td><td>any city with name "Nnnn" in region "Rrrr" and any subregion of the country with code "CC"</td></tr>
<tr><td>CCRrrr,Ssss,Nnnn</td><td>any city with name "Nnnn" in region "Rrrr" and subregion "Ssss" of the country with code "CC"</td></tr>
<tr><td>CC,</td><td>the country with code "CC"</td></tr>
<tr><td>CCRrrr,</td><td>the region "Rrrr" in the country with code "CC"</td></tr>
<tr><td>CCRrrr,Ssss,</td><td>the subregion "Ssss" in region "Rrrr" of the country with code "CC"</td></tr>
</table></blockquote>

Entries in the table above are ordered from lowest priority at the top to
highest at the bottom, with the match of highest priority taking precedence when
translating a name.</blockquote>

<blockquote>User-defined language translations may be added for the default 'en'
language to affect the returned names when no language is specified.</blockquote>

<hr>
<a name="Troubleshooting"></a>
<h3>Troubleshooting</h3>

<a name="TR1"></a>
<p>1. <b>"ExifTool returns an unexpected city for the specified GPS coordinates"</b></p>

<blockquote>First, try listing a number of nearby cities to see if ExifTool is
just finding something closer.  For example the following command lists the
10 cities nearest to a specified GPS position, where "LAT" and "LON" are signed
floating-point latitude and longitude:

<pre>exiftool -api geolocation=LAT,LON,num=10 -a -g3</pre>

If the expected city is in this list, take note of the feature codes and populations
of these cities.  The API <a href="ExifTool.html#GeolocFeature">GeolocFeature</a>
and API <a href="ExifTool.html#GeolocMinPop">GeolocMinPop</a> options may be used
to limit the feature types and/or population of the returned cities according
to your requirements.  For example, to avoid returning PPLX city types and cities
with population less than 10000, you could do this:

<pre>exiftool -api geolocfeature=-PPLX -api geolocminpop=10000 ...</pre>

However, if your city doesn't appear in the list, then it is likely that it
doesn't exist in the ExifTool Geolocation database.  You can  check this by
searching for the specific city in the ExifTool database.  This command returns
all cities with name "CITYNAME" exactly (case insensitive):

<pre>exiftool -api geolocation="CITYNAME" -m -a -g3</pre>

or this command may be used to match cities with "STRING" anywhere in their name
(the added "<code>i</code>" makes the match case insensitive):

<pre>exiftool -api geolocation="ci/STRING/i" -m -a -g3</pre>

A city may not appear in the ExifTool Geolocation database if the population
is lower than a minimum, which is 2000 for the standard database.  An
<a href="#Alt">alternate database</a> is available with cities down to population
500, but it may be a good idea to first see if the city exists in the source
geonames.org database.  Use the search field <a href="https://www.geonames.org">here</a>
to 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).</blockquote>

<blockquote>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 update
their database with the correct information.  This information will eventually
propagate down to ExifTool (probably within a few months), or you can build your
own <a href="#Alt">alternate database</a>.  Or 2. Create a
<a href="#Custom">user-defined entry</a> for your city in the ExifTool config file.
</blockquote>

<hr>
<i>Created Mar 12, 2024</i><br>
<i>Last revised Mar 11, 2025</i>
<p class='lf'><a href="index.html">&lt;-- Back to ExifTool home page</a></p>
</body>
</html>