View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Leo Lapworth > Geo-Postcode-0.17 > Geo::Postcode::Location



Annotate this POD


New  2
Open  0
View/Report Bugs
Module Version: 0.12   Source  


Geo::Postcode::Location - helper class for Geo::Postcode that handles grid reference lookups


  $Geo::Postcode::Location::datafile = '/usr/local/lib/postcodes.db';
  my ($x, $y) = Geo::Postcode->coordinates('EC1R 8BB');


Geo::Postcode::Location holds the gridref-lookup functions of Geo::Postcode. It is separated here to minimise the footprint of the main module and to facilitate subclassing.

It doesn't really have a useful direct interface, since it requires an object of Geo::Postcode (or a subclass) and is most easily reached through that object, but it does have a couple of configuration variables and there is method documentation here for anyone interested in subclassing it or changing the data source.


There are at least three ways to supply your own gridref data.


new ()

Constructs and returns a location object. Must be supplied with a postcode object of the class dictated by postcode_class.

postcode_class ()

Returns the full name of the postcode class we should be expecting.

postcode ()

Returns the postcode object used to construct this object.

retrieve ()

Retrieves location information for this postcode. This method is called during construction, retrieves all the necessary information in one go, so all the rest have to do is look up internal values.

disconnect_after_use ()

If this returns a true value, then dbh->disconnect will be called after location information is retrieved.

dbh ()

Accepts, returns - and creates, if necessary - the DBI handle that will be used to retrieve location information.

This is only separate to make it easy to override.

datafile ( path_to_file )

Accepts and returns the location of the SQLite file we expect to provide location data.

If no file path is supplied, or found by checking $Geo::Postcode::Location::datafile and $ENV{POSTCODE_DATA}, then we will scan the path to locate the default data file that is installed with this module.

tablename ()

Sets and gets the name of the database table that should be expected to hold postcode data.

cols ()

Returns a list of the columns we should pull from the database row into the location object's internal hash (and also provide as instance methods). This isn't used in the SQL query (which just SELECTs *), so we don't mind if columns are missing.


Turns the columns defined by cols into lookup methods. You can't set values this way: the whole module is strictly read-only.

gridref ()

Returns a proper concatenated grid reference for this postcode, in classic Ordnance Survey AA123456 form rather than the all-digits version we use internally.

See or the more sober

for more about grid references.

Unlike other grid methods here, this one will also strip redundant trailing zeros from the eastings and northings for the sake of readability.

distance_from ()

We prefer to use grid references to calculate distances, since they're laid out nicely on a flat plane and don't require us to remember our A-levels. This method just returns a single distance value.

You can specify the units of distance by setting $Geo::Postcode::Location::units or passing in a second parameter. Either way it must be one of 'miles', 'km' or 'm'. The default is 'km'.

bearing_to ()

Returns the angle from grid north, in degrees clockwise, of the line from this postcode to the postcode object supplied.

friendly_bearing_to ()

Returns a readable approximation of the bearing from here to there, in a form like 'NW' or 'SSE'.


William Ross,


Copyright 2004 William Ross, spanner ltd.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: