File Coverage

File:blib/lib/Geo/Coder/Free/Provenance.pm
Coverage:100.0%

linestmtbrancondsubpodtimecode
1package Geo::Coder::Free::Provenance;
2
3# The provenance of a result, and the vocabulary it speaks.  Kept out of
4# Geo::Coder::Free::Utils, which is tracked from VWF master: a geocoder result
5# has no provenance there, so an addition to that file lasts only until the next
6# sync with upstream.  Everything in this module is specific to this
7# distribution.
8
9
20
20
20
20
85692
14
256
use strict;
10
20
20
20
20
28
13
362
use warnings;
11
12
20
20
20
20
30
8384
173
use Geo::Location::Point 0.19 ();       # Defines the accuracy vocabulary this module speaks
13
20
20
20
20
29
18
583
use Exporter qw(import);
14our @EXPORT_OK = qw(GEOCODER ACCURACY_LEVELS);
15
16=encoding utf-8
17
18 - 48
=head1 NAME

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

=head1 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
F<BI-Phase6-Dependency-Specs.md>, and the vocabulary they speak.

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

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

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

These two live here rather than in L<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.

=head1 VERSION

Version 0.51

=cut
49
50our $VERSION = '0.51';
51
52# The distribution that produced a result.  Every backend stamps this on the
53# Geo::Location::Point it hands back, so a consumer can tell a result from this
54# distribution from one passed on by a wrapper such as Geo::Coder::List.
55# Section 2.1 of BI-Phase6-Dependency-Specs.md.
56
20
20
20
20
39
14
558
use constant GEOCODER => 'Geo::Coder::Free';
57
58# How precise the coordinates behind a match can claim to be, most precise
59# first.  Geo::Location::Point::accuracy_for() returns one of these, and anything
60# that validates an accuracy (section 3.2) validates against this list.
61#
62# The vocabulary is not written down here.  Geo::Location::Point defines it and
63# refuses an accuracy outside it, so this module reads that one list: the levels
64# a backend reports and the levels a point accepts cannot drift apart, and this
65# constant is the same list object rather than a copy that agrees today.  The
66# rule that turns matched fields into a level lives there too, with the list.
67
20
20
20
20
30
17
33
use constant ACCURACY_LEVELS => Geo::Location::Point::ACCURACY_LEVELS();
68
69 - 92
=head1 SUBROUTINES/METHODS

=head2 GEOCODER

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

=head2 ACCURACY_LEVELS

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

It is C<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.

The rule that turns the fields a match was made on into one of these levels is
C<Geo::Location::Point::accuracy_for()>, which lives beside the list it returns
a level from.  This module reports the C<accuracy> key; it does not decide what
the key may hold.

=cut
93
941;
95