Image::...ocation(3)

📦
version 13.50 · 11 versions
, in fedora 43, fedora 44

💖 Image::ExifTool::Geolocation 💖

bestie. sit down. this one's from the User Contributed Perl Documentation and the page is called Image::ExifTool::Geolocation(3) (the header's a little truncated, she's shy). no cap, it's genuinely so useful.

✨ NAME ✨

Image::ExifTool::Geolocation — Determine geolocation from GPS and visa-versa 🗺️✨

🌸 SYNOPSIS 🌸

Look up geolocation info (city, region, subregion, country, etc) based on input GPS coordinates, or determine GPS coordinates based on city name, etc. both directions, icon behavior 💅

🦋 DESCRIPTION 🦋

This module has 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. she's on a diet and she ate 💅

👑 METHODS 👑

💖 ReadDatabase

Load the Geolocation database from a file. This method gets called automatically when this module is loaded — no manual labor required, bestie.

By default, the database is loaded from Geolocation.dat in the same directory as this module. But! you can use a different directory by setting $Image::ExifTool::Geolocation::geoDir before loading this module. Setting it to an empty string avoids loading any database at all. If the file can't be read, a warning is generated. ⚠️

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

Inputs:

  • 0) Database file name

Return Value:

True on success. ✅

🌈 ReadAltNames

Load the alternate names database. Before you call 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. she shows up uninvited but like, in a helpful way 🫶

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

Inputs:

  • (none) — she needs nothing from you

Return Value:

True on success. May be called repeatedly, but AltNames.dat is loaded only on the first call. efficient queen 👑

⭐ SortDatabase

Sort the database in the specified order.

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

Inputs:

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

Return Value:

1 on success, 0 on failure (bad sort order specified). 😭

🎀 AddEntry

Add an entry to the 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. she updates herself, self-care ✨
  • 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 an entry from the 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 a 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. no skipping steps, bestie 🚨

🧚 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, or when a single city is matched by name, return the nearest ## cities instead of just the closest or named 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.

In scalar context, only the reference to the list of database entry numbers is returned. scalar context stays minimal, she's lowkey 💅

🌍 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. must match, no vibes-based matching allowed 😤

🫶 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-2026, 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. free and open, the way we like it 💚

🔥 REFERENCES 🔥

🌟 SEE ALSO 🌟

and that's the whole page bestie, we ate, no crumbs left 🍓✨ this was perl v5.42.1, dated 2026-03-31 — go forth and geolocate responsibly, ily 💖🦋🎀

📦 where this page comes from