File Coverage

blib/lib/Geo/LookupPostcode.pm
Criterion Covered Total %
statement 27 27 100.0
branch 2 4 50.0
condition n/a
subroutine 7 7 100.0
pod 1 1 100.0
total 37 39 94.8


line stmt bran cond sub pod time code
1             package Geo::LookupPostcode;
2              
3 2     2   29587 use 5.012;
  2         4  
4 2     2   6 use strict;
  2         2  
  2         54  
5 2     2   6 use warnings FATAL => 'all';
  2         4  
  2         64  
6 2     2   514 use utf8;
  2         8  
  2         9  
7              
8 2     2   883 use Module::Load;
  2         1454  
  2         10  
9 2     2   79 use Carp qw(croak);
  2         3  
  2         545  
10             require Exporter;
11              
12             our @ISA = qw(Exporter);
13             our @EXPORT_OK = qw(lookup_postcode);
14              
15             # These are initialised further down
16             my %lookup_table;
17             my %lookup_functions;
18              
19             =encoding utf-8
20              
21             =head1 NAME
22              
23             Geo::LookupPostcode - Get province data for a given postcode
24              
25             =head1 VERSION
26              
27             Version 0.01_02
28              
29             This is a developer release, as the API interface may change.
30              
31             =cut
32              
33             our $VERSION = '0.01_02';
34              
35              
36             =head1 SYNOPSIS
37              
38             Given a country name and a postcode, get which province or region or area it
39             refers to.
40              
41             use Geo::LookupPostcode qw(lookup_postcode);
42              
43             my $province = lookup_postcode("it", "00118");
44             # $province is now:
45             # {
46             # region_code => 'IT-62',
47             # province_code => 'IT-RM',
48             # }
49              
50             If you prefer, you can use country-specific modules, it is the same result in
51             either case.
52              
53             use Geo::LookupPostcode::IT;
54             my $province = lookup_it_postcode("00118");
55              
56             =head1 Supported countries
57              
58             =over 12
59              
60             =item Italy
61              
62             This includes the Vatican and the Republic of San Marino.
63              
64             L
65              
66             =item Spain
67              
68             L
69              
70             =item Finland
71              
72             L
73              
74             =back
75              
76             =head1 SUBROUTINES/METHODS
77              
78             =head2 lookup_postcode
79              
80             Takes two character string arguments, the first one being a two-letter ISO
81             3166-1 country code, and the second one being a postcode in that country.
82              
83             If successful, it returns a reference to a hash. The keys depend on the
84             country. In the case of Italy, it would return this structure:
85              
86             {
87             region_code => $region_code,
88             province_code => $province_code,
89             }
90            
91             If it cannot find the province, it returns undef.
92              
93             Note that the names may be anglicised (eg: "Vatican City", not "Città del Vaticano").
94              
95             This subroutine will die if the wrong number of arguments is passed or if an
96             unsupported country is passed.
97              
98             my $rh_province = lookup_postcode("it", "00118");
99              
100             =cut
101              
102             sub lookup_postcode {
103 100002 50   100002 1 8987291 croak "Expected two arguments" if (@_ != 2);
104 100002         95905 my ($country, $postcode) = @_;
105              
106 100002 50       221220 croak "Country $country in unexpected format" if $country !~ /^[a-z]{2}$/i;
107              
108 100002         82434 my $uc_country = uc($country);
109 100002         74004 my $lc_country = lc($country);
110 100002         92412 my $module = "Geo::LookupPostcode::$uc_country";
111 100002         154488 load $module;
112 100002         2891977 my $subroutine = \&{"${module}::lookup_${lc_country}_postcode"};
  100002         227101  
113 100002         163119 return $subroutine->($postcode);
114             }
115              
116              
117              
118             =head1 AUTHOR
119              
120             David D Lowe, C<< >>
121              
122             =head1 SUPPORT
123              
124             You can find documentation for this module with the perldoc command.
125              
126             perldoc Geo::LookupPostcode
127              
128             You can also look for information at:
129              
130             =over 4
131              
132             =item * GitHub issue tracker (report bugs here)
133              
134             L
135              
136             =item * AnnoCPAN: Annotated CPAN documentation
137              
138             L
139              
140             =item * CPAN Ratings
141              
142             L
143              
144             =item * Search CPAN
145              
146             L
147              
148             =back
149              
150             =head1 SEE ALSO
151              
152              
153             L, L and L provides UK
154             postcode validation and location.
155              
156             L provides USA postal code functions.
157              
158             L provides an abstract interface for looking up postcodes. The
159             only two implementations that I am aware of are L and
160             L, for Norway and Denmark.
161              
162              
163             =head1 ACKNOWLEDGEMENTS
164              
165             Most of the data was sourced from Wikipedia.
166              
167             =head1 LICENSE AND COPYRIGHT
168              
169             Copyright 2016 David D Lowe and contributors.
170              
171             This work is licensed under CC BY-SA 3.0.
172              
173             =cut
174              
175             1; # End of Geo::LookupPostcode