1. Manuals
  2. Tumbleweed
  3. perl-Image-ExifTool
  4. Image::ExifTool::Geolocation(3pm)

Scroll to navigation

Image::ExifTool::Geolocation(3) User Contributed Perl Documentation Image::ExifTool::Geolocation(3)

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);
0) Database file name
True on success.

ReadAltNames

Load the alternate names database. Before calling this method the $altDir package variable must be set to a directory containing the AltNames.dat database that matches the current Geolocation.dat. This method is called automatically by "Geolocate" if $altDir is set and the GeolocAltNames option is used and an input city name is provided.

    Image::ExifTool::Geolocation::ReadAltNames();
(none)
True on success. Resets the value of $altDir to prevent further attempts at re-loading the same database.

SortDatabase

Sort database in specified order.

    Image::ExifTool::Geolocation::ReadDatabase('City');
0) Sort order: 'Latitude', 'City' or 'Country'
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);
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

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);
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

GetAltNames

Get alternate names for specified city.

    my $str = Image::ExifTool::Geolocation::GetAltNames($num,$sort);
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

Comma-separated string of alternate names for this city.
Must set the $altDir package variable and call "ReadAltNames" before calling this routine.

Geolocate

Return geolocation information for specified GPS coordinates or city name.

    my @rtnInfo = Image::ExifTool::Geolocation::Geolocate($arg,$opts);
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) Optional reference to hash of options:

   GeolocMinPop   - minimum population of cities to consider in search
   GeolocMaxDist  - maximum distance (km) to search for cities when an input
                    GPS position is used
   GeolocMulti    - 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.
   GeolocFeature  - comma-separated list of feature codes to include in
                    search, or exclude if the list starts with a dash (-)
   GeolocAltNames - flag to search alternate names database if available
                    for matching city name (see ALTERNATE DATABASES below)
0) Number of matching entries, or 0 if no matches

1) Entry number for matching city in database, or undef if no matches, or a reference to a list of entry numbers of matching cities if multiple matches were found and the flag was set to return multiple matches

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

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

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.

A database of alternate city names may be loaded by setting the package $altDir variable. This directory should contain the AltNames.dat database that matches the version of Geolocation.dat being used. When searching for a city by name, the alternate-names database is checked to provide additional possibilities for matches.

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
         '',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>

SEE ALSO

Image::ExifTool(3pm)

2024-04-10 perl v5.38.2