/ 
Geo-Coder-Free-0.47
⭐ Starred 9 / Geo::Coder::Free::Provenance

NAME

Geo::Coder::Free::Provenance - The provenance keys that every Geo::Coder::Free result carries

DESCRIPTION

Which distribution and which backend produced a result, how good the match was and how precise the coordinate is: the keys of section 2.1 of BI-Phase6-Dependency-Specs.md, and the vocabulary they speak.

use Geo::Coder::Free::Provenance qw(GEOCODER _accuracy_for);

my $point = Geo::Location::Point->new({
    geocoder   => GEOCODER,
    database   => 'OpenAddresses',
    confidence => 1.0,
    accuracy   => _accuracy_for(qw(house_number road city)),
});

Geo::Coder::Free->provenance($point) reads the four keys back, so a consumer does not have to know them.

These three live here rather than in Geo::Coder::Free::Utils because Utils is synced from VWF master, where the provenance of a geocoder result has no meaning; an addition there would be lost the next time that sync runs.

VERSION

Version 0.47

SUBROUTINES/METHODS

GEOCODER

The distribution that produced a result: Geo::Coder::Free. It is the geocoder key of every result this distribution returns, whether the answer came from OpenAddresses, Local or MaxMind.

ACCURACY_LEVELS

A list of the accuracies a result may claim, most precise first: address, street, postcode, locality, city, region and country.

It is Geo::Location::Point::ACCURACY_LEVELS(), the list that module validates an accuracy against, re-exported here so that a backend can describe the match it made without knowing which module the vocabulary is defined in. There is one list behind both names, not a copy of it.

_accuracy_for

The precision a match can claim, from the fields that made it. The most precise field present decides: a house number makes it an address, a road a street, a postcode a postcode, a name or a city a locality, a state or region a region, and a country a country. So a dataset row carrying only a city, state and country is a locality, which is what the geographic centres Local.pm derives are.

Always returns one of the ACCURACY_LEVELS: a match on a row with none of the fields above is still a named place, so it is reported as a locality rather than left unsaid, because every result promises an accuracy.

Exported so that a backend can describe the match it made without repeating the vocabulary.

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENSE AND COPYRIGHT

Copyright 2017-2026 Nigel Horne.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2.