tipichris edited this page Sep 14, 2010 · 9 revisions

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.


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.


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.


Indicates that the geo data is in osgb36 (British national grid) format.This is the default. Note that the uk_postcodes driver (which uses 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)


returns the last error message generated
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.