Image::ExifTool::Geolocation(3)

NAME
Image::ExifTool::Geolocation - Look up geolocation based on GPS position

SYNOPSIS
This module is used by the Image::ExifTool Geolocation feature.

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.

  SortDatabase
Sort database in specified order.

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

Inputs:
    0) Sort order: 'Longitude', '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,
        $countryCode, $country, $timezone, $population, $lat, $lon);

Inputs:
    0) GPS latitude (signed floating point degrees)

    1) GPS longitude

    2) City name (UTF8)

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

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

    5) 2-character ISO 3166 country code

    6) 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.

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

    8) City population

  GetEntry
Get entry from Geolocation database.

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

Inputs:
    0) Entry number in database

    1) Optional language code

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) City population

    7) GPS latitude

    8) GPS longitude

Notes:
    The alternate-language feature of this method (and of "Geolocate") requires the installation of optional GeoLang modules. See <https://exiftool.org/geolocation.html> for more information.

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

    my @cityInfo =
        Image::ExifTool::Geolocation::Geolocate($arg,$pop,$dist,$lang,$multi);

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. See <https://exiftool.org/geolocation.html#Read> for details.

    1) Minimum city population (cities smaller than this are ignored)

    2) Maximum distance to city (farther cities are not considered)

    3) Language code

    4) Flag to return multiple cities if there is more than one match. In this case the return value is a list of city information lists.

Return Value:
    Reference to list of information about the matching city. If multiple matches were found, the city with the highest population is returned unless the flag is set to allow multiple cities to be returned, in which case all cities are turned as a list of city lists in order of decreasing population.

    The city information list contains the following entries:

    0) Name of matching city (UTF8), or undef if no match

    1) Region, state or province name (UTF8), or "" if no region

    2) Subregion name (UTF8), or "" if no region

    3) Country code

    4) Country name (UTF8)

    5) Standard time zone identifier name

    6) City population rounded to 2 significant figures

    7) Approximate city latitude (signed degrees)

    8) Approximate city longitude

    9) Distance to city in km if "lat,lon" specified

    10) Compass bearing for direction to city if "lat,lon" specified

    11) Flag set if multiple matches were found

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;

CUSTOM LANGUAGE TRANSLATIONS
User-defined language translations may be added by defining %Image::ExifTool::Geolocation::geoLang before calling GetEntry() or Geolocate(). See <http://exiftool.org/geolocation.html#Custom> for details.

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. Geolocation.dat is based on data from geonames.org with a Creative Commons license.

REFERENCES

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

SEE ALSO
Image::ExifTool(3pm)