Ubuntu Manpage: Image::ExifTool::Geolocation - Determine geolocation from GPS and visa-versa

Provided by: libimage-exiftool-perl_13.10+dfsg-1_all

NAME

       Image::ExifTool::Geolocation - Determine geolocation from GPS and visa-versa

SYNOPSIS

       Look up geolocation information (city, region, subregion, country, etc) based on input GPS coordinates,
       or determine GPS coordinates based on city name, etc.

DESCRIPTION

       This module contains the code to convert GPS coordinates to city, region, subregion, country, time zone,
       etc.  It uses a database derived from geonames.org, modified to reduce the size as much as possible.

METHODS

ReadDatabase
Load Geolocation database from file. This method is called automatically when this module is loaded. By
default, the database is loaded from "Geolocation.dat" in the same directory as this module, but a
different directory may be used by setting $Image::ExifTool::Geolocation::geoDir before loading this
module. Setting this to an empty string avoids loading any database. A warning is generated if the file
can't be read.

Image::ExifTool::Geolocation::ReadDatabase($filename);

Inputs:
0) Database file name

Return Value:
True on success.

ReadAltNames
Load the alternate names database. Before calling this method the $altDir package variable may be set,
otherwise AltNames.dat is loaded from the same directory as Geolocation.dat. This method is called
automatically by "Geolocate" if the GeolocAltNames option is used and an input city name is provided.

Image::ExifTool::Geolocation::ReadAltNames();

Inputs:
(none)

Return Value:
True on success. May be called repeatedly, but AltNames.dat is loaded only on the first call.

SortDatabase
Sort database in specified order.

Image::ExifTool::Geolocation::ReadDatabase('City');

Inputs:
0) Sort order: 'Latitude', 'City' or 'Country'

Return Value:
1 on success, 0 on failure (bad sort order specified).

AddEntry
Add entry to Geolocation database.

Image::ExifTool::Geolocation::AddEntry($city, $region,
$subregion, $countryCode, $country, $timezone,
$featureCode, $population, $lat, $lon, $altNames);

Inputs:
0) City name (UTF8)

1) Region, state or province name (UTF8), or empty string if unknown

2) Subregion name (UTF8), or empty string if unknown

3) 2-character ISO 3166 country code

4) Country name (UTF8), or empty string to use existing definition. If the country name is provided
for a country code that already exists in the database, then the database entry is updated with the
new country name.

5) Time zone identifier (eg. "America/New_York")

6) Feature code (eg. "PPL"), or empty if not known

7) City population

8) GPS latitude (signed floating point degrees)

9) GPS longitude

10) Optional comma-separated list of alternate names for the city

Return Value:
1 on success, otherwise sends a warning message to stderr

GetEntry
Get entry from Geolocation database.

my @vals = Image::ExifTool::Geolocation::GetEntry($num,$lang,$sort);

Inputs:
0) Entry number in database, or index into sorted database

1) Optional language code

2) Optional flag to treat first argument as an index into the sorted database

item Return Values:

0) City name, or undef if the entry didn't exist

1) Region name, or "" if no region

2) Subregion name, or "" if no subregion

3) Country code

4) Country name

5) Time zone

6) Feature code

7) City population

8) GPS latitude

9) GPS longitude

10) Feature type, or undef

GetAltNames
Get alternate names for specified city.

my $str = Image::ExifTool::Geolocation::GetAltNames($num,$sort);

Inputs:
0) Entry number in database or index into the sorted database

1) Optional flag to treat first argument as an index into the sorted database

Return value:
Comma-separated string of alternate names for this city.

Notes:
"ReadAltNames" must be called before calling this routine.

Geolocate
Return geolocation information for specified GPS coordinates or city name.

my @rtnInfo = Image::ExifTool::Geolocation::Geolocate($arg,$opts);

Inputs:
0) Input argument ("lat,lon", "city", "city,country", "city,region,country", etc). When specifying a
city, the city name must come first, followed by zero or more of the following in any order,
separated by commas: region name, subregion name, country code, and/or country name. Regular
expressions in "/expr/" format are also allowed, optionally prefixed by "ci", "re", "sr", "cc" or
"co" to specifically match City, Region, Subregion, CountryCode or Country name. Two special
controls may be added to the argument list:

'both' - When search input includes both name and GPS coordinates, use
both to determine the closest city matching the specified
name(s) instead of using GPS only.

'num=##' - When the search includes GPS coordinates, return the nearest
## cities instead of just the closest one. Returned cities
are in the order from nearest to farthest.

See <https://exiftool.org/geolocation.html#Read> for more details.

1) Optional reference to hash of options:

GeolocMinPop - Minimum population of cities to consider in search.
Default 0.

GeolocMaxDist - Maximum distance (km) to search for cities when an
input GPS position is used. Default infinity.

GeolocMulti - Flag to return multiple cities if there is more than
one match. Used in the case where no input GPS
coordinates are provided. Default 0.

GeolocFeature - Comma-separated list of feature codes to include in
search, or exclude if the list starts with a dash (-).
Default undef.

GeolocAltNames - Flag to search alternate names database if available
for matching city name (see ALTERNATE DATABASES below).
Default undef.

Return Values:
0) Reference to list of database entry numbers for matching cities, or undef if no matches were
found.

1) Reference to list of distance/bearing pairs for each matching city, or undef if the search didn't
provide GPS coordinates.

ALTERNATE DATABASES

       A  different  version of the cities database may be specified setting the package $geoDir variable before
       loading this module.  This directory should contain the Geolocation.dat file, and  optionally  a  GeoLang
       directory  for  the language translations.  The $geoDir variable may be set to an empty string to disable
       loading of a database.

       When searching for a city by name, AltNames.dat  is  checked  to  provide  additional  possibilities  for
       matches  if  the  GeolocAltNames  option is set and an AltNames.dat database exists.  The package $altDir
       variable may be set to specify a different directory  for  AltNames.dat,  otherwise  the  Geolocation.dat
       directory  is  assumed.   The entries in AltNames.dat must match those in the currently loaded version of
       Geolocation.dat.

ADDING USER-DEFINED DATABASE ENTRIES

       User-defined entries may be created by defining them using the following technique before the Geolocation
       module is loaded.

           @Image::ExifTool::UserDefined::Geolocation = (
               # city, region, subregion, country code, country, timezone,
               ['Sinemorets','burgas','Obshtina Tsarevo','BG','','Europe/Sofia',
               # feature code, population, lat, lon
                'PPL',400,42.06115,27.97833],
           );

       Similarly,  user-defined  language  translations  may  be  defined,  and  will  override   any   existing
       translations.    Translations   for   the   default   'en'   language   may   also   be  specified.   See
       <https://exiftool.org/geolocation.html#Custom> for more information.

USING A CUSTOM DATABASE

       This example shows how to use a custom database.  In this example, the input database file  is  a  comma-
       separated text file with columns corresponding to the input arguments of the AddEntry method.

           $Image::ExifTool::Geolocation::geoDir = '';
           require Image::ExifTool::Geolocation;
           open DFILE, "< $filename";
           Image::ExifTool::Geolocation::AddEntry(split /,/) foreach <DFILE>;
           close DFILE;

AUTHOR

       Copyright 2003-2024, Phil Harvey (philharvey66 at gmail.com)

       This  library  is  free  software;  you can redistribute it and/or modify it under the same terms as Perl
       itself.  The associated database files are based on  data  from  geonames.org  with  a  Creative  Commons
       license.

REFERENCES

       <https://download.geonames.org/export/>
       <https://exiftool.org/geolocation.html>