Methods

factory(string $driver, array $params)

Create a new instance. $driver is the driver to be used, currently one of ‘textfile’, ‘mysql’, ‘uk_postcodes’, ‘ukgeocode’, ‘geopostcode’ or ‘openlylocal’. Valid values for $params depend on the driver chosen. See Drivers for more information.

loaddata()

Initialise the connection to the back end. This must always be called before any functions needing to look up postcodes can be called.

set_inoutsep(string $sep)

Sets the value of the separator between outward (SW1A) and inward (1AA) parts of the postcode data. The default depends on the driver. It is a single space usually, but an empty string for uk_postcodes. The use of an empty string is not recommended if your data also includes means or midpoints for districts and sectors, because this can be ambiguous. Eg ‘B11’ could be either the district B11 or the sector B1 1.

use_wgs84()

Indicates that the geo data is in wgs84 (latitude and longitude) format. Note that when using the mysql driver if you do not specify the sql parameter in the paramaters passed to factory() and you are using wgs84 you must call use_wgs84() before calling loaddata. This is because the default SQL is dependent on the co-ordinate scheme being used.

use_osgb36()

Indicates that the geo data is in osgb36 (British national grid) format.This is the default. Note that the uk_postcodes driver (which uses http://www.uk-postcodes.com) can provide data in either wgs84 or osgb36. The latter makes distance calculations less demanding

validcode(string $postcode [, boolean $exactmatch])

Tests if a postcode is valid and known in the database. Returns the found code on success, false on failure. If the full code is not found, checks will be made for matches by sector (SW1A 1), district (SW1A) and area (SW1). The return value is the best match.

If $exactmatch is true (defaults to false), matches only if the $postcode is known (after normalising $postcode).

set_grain(int $grain)

Sets the smallest unit that will be checked for by validcode() 1: Area only: SW 2: District: SW1A 3: Sector: SW1A 1 4: Unit: SW1A 1AA

getgeodata(string $postcode)

Returns an array containing the location of the postcode. The elements are (eastings, northings) for osgb36 or (latitude, longitude) for wgs84

splitpostcode(string $postcode)

Takes a postcode or partial postcode and attempts to split it into component parts. Returns an array:

      [0] => Area,
      [1] => District
      [2] => Sector
      [3] => Unit

eg, for SW1A 1AA

      [0] => SW
      [1] => 1A
      [2] => 1
      [3] => AA

Returns false on failure

samepostcode(string $postcode1, string $postcode2)

Checks if $postcode1 is the same postcode as $postcode2. Returns true if the same, false otherwise

normalise ($postcode)

Returns a normalised version of $postcode, taking account of the current setting of $inoutsep

calc_distance (string $fromcode, string $tocode[, array $options])

calculate the distance between $fromcode and $tocode. $options is an optional array:

    unit => 'miles'|'km'    The unit to return the distance in (default miles)
    decimal => int  The number of decimal places (defalt 0)

Like validcode(), if an exact match isn’t available calc_distance will match on sector, district or area. Returns false on failure.

NB 0 is a valid, good response indicating a distance of 0km or 0miles. Be sure to test for false (eg if($d === false)

lasterror()

returns the last error message generated