jQuery Plugin

Our jQuery plugin is the easiest way to integrate postcode lookups on a web page.

Step 1 - Sign up for your account

You can either sign up for a FREE trial account which lasts for 20 days, or use your live account.

You will need your API key to use the jQuery plugin (check your order email or login to your account).

Step 2 - Plugin References

Add a jQuery library reference within the head tags of your web page if it doesn't contain one.

<script src="http://code.jquery.com/jquery-1.10.2.min.js"></script>


Add a reference to our plugin within the head tags of your web page.

<script src="http://www.postcodesoftware.net/lookup.min.js"></script>

Step 3 - Form Elements & Configuration Object

Simply copy and paste the code below into your website then add your API key to start performing address lookups.

<div id="postcode_lookup"></div> <input id="line1" type="text" placeholder="Address" /> <input id="line2" type="text" placeholder="Address Line 2" /> <input id="line3" type="text" placeholder="Address Line 3" /> <input id="line4" type="text" placeholder="Address Line 4" /> <input id="town" type="text" placeholder="Town" /> <input id="postcode" type="text" placeholder="Postcode" /> <script> $('#postcode_lookup').getAddress({ api_key: 'your_key_goes_here', output_fields: { // Form element ID's have been added below line1: '#line1', line2: '#line2', line3: '#line3', line4: '#line4', town: '#town', postcode: '#postcode' } }); </script>

Address Fields

Name Description
line1 Often contains premise and thoroughfare information
If the addresses organisation field is populated then line1 is always the organisation name.
Never empty
line2 Often contains thoroughfare and locality information
Might be empty
line3 Can contain thoroughfare and locality information
Might be empty
line4 Can contain thoroughfare and locality information
Might be empty
town A post town will always be present in every address, and for some localities the post town will be the only locality element present
Never empty
county The county is no longer required as part of a correct postal address provided the post town and postcode are included
Never empty
postcode Capitalised and correctly spaced
Never empty
organisation Name of the organisation
E.g. Cyclops Software Ltd
Block Complete address minus county displayed across multiple lines
 
E.g. Cyclops Software Ltd
Osborne House
20 Victoria Avenue
Harrogate
HG1 5QY

Working example
line Complete address minus county displayed across a single line
E.g. Cyclops Software Ltd, Osborne House, 20 Victoria Avenue, Harrogate, HG1 5QY

Address lines can be reduced by removing line4 or a combination of line4, line3, line2. Address elements will be automatically restructured in a logical manor.
E.g.

output_fields: {
    line1: '#line1',
    line2: '#line2',
    line3: '#line3',
    town: '#town',
    postcode: '#postcode'
}
output_fields: {
    line1: '#line1',
    line2: '#line2',
    town: '#town',
    postcode: '#postcode'
}
output_fields: {
    line1: '#line1',
    town: '#town',
    postcode: '#postcode'
}

Options

Name Description
api_key Unique Key consisting of 16 randomly generated characters
Mandatory
validation_text Must match the validation text stored within the account associated with the API key
button Set to 'true' for a search button
search Set as a unique identifier if using multiple searches on the same page
organisation Set as 'false' to exclude all addresses with a populated organisation field
line1_no_organisation Set as 'true' to not show the organisation within line1
block_no_organisation Set as 'true' to not show the organisation within block
line_no_organisation Set as 'true' to not show the organisation within line
complete Use to call a custom function - Will only fire for valid postcodes
style Set as a number from 1 - 5 for predefined styles
  • For multiple searches, add the 'style' option to the last search on the page and all searches will be effected
  • Set as 'false' for no default css styling
  • Must be applied to all searches if used

  • .dropdownstyle
  • .dropdowncontentstyle
  • .optionstyle
  • .notice

You can manage your account settings here.

HTTP Referer

Your API key can be locked to a specific website(s) by adding its address to the referrer section within your account.
Any text entered within the referrer section will be searched for within the address of the website making the lookup request.
A semi colon (;) can be used to separate multiple referrer text values when you need to use your API key on multiple websites.

Please see the table below for further clarification.

Referrer text Website making the request Valid?
postcodesoftware.co.uk www.postcodesoftware.co.uk Yes
www.postcodesoftware.net No
postcodesoftware www.postcodesoftware.co.uk Yes
www.postcodesoftware.net Yes
www.royalmail.com No
postcodesoftware;royalmail www.postcodesoftware.co.uk Yes
www.postcodesoftware.net Yes
www.royalmail.com Yes
www.poweredbypaf.com No

Any other sites attempting to make a lookup request using your API key will be presented with the following message 'Referrer does not match'. Please note if the address of the website making the request cannot be obtained the lookup will be allowed to occur.

Validation Text

Validation text can be passed as an option within the configuration object. This will need to match the corresponding validation text set within your account. An incorrect match will give the following response 'Validation Text does not match'

<script> $('#postcode_lookup').getAddress({ api_key: 'your_key_goes_here', // Validation Text option validation_text: 'Licensed for sole use by PostcodeSoftware', output_fields: { line1: '#line1', line2: '#line2', line3: '#line3', line4: '#line4', town: '#town', postcode: '#postcode' } }); </script>

Company Name

Your company name will be automatically displayed along the bottom of the search results dropdown.
E.g. 'PAF data licensed to PostcodeSoftware'

The examples found below use our test acount API key and will only work with LS18 postcodes.
LS18 4AA • LS18 4AB • LS18 4AD • LS18 4AE • LS18 4AF • LS18 5SF • LS18 5SG • LS18 5SH • LS18 5SJ • LS18 5SL

Auto Search

<!-- Postcode Field -->
<div id="postcode_lookup"></div>
<!-- Address Fields -->
<input id="line1" type="text" placeholder="Address Line 1" />
<input id="line2" type="text" placeholder="Address Line 2" />
<input id="line3" type="text" placeholder="Address Line 3" />
<input id="line4" type="text" placeholder="Address Line 4" />
<input id="town" type="text" placeholder="Town" />
<input id="postcode" type="text" placeholder="Postcode" />
<!-- Add below form -->
<script>
    $('#postcode_lookup').getAddress({
        api_key: 'Enter-your-API-key',
        output_fields: {
            line1: '#line1',
            line2: '#line2',
            line3: '#line3',
            line4: '#line4',                                        
            town: '#town',
            postcode: '#postcode',
        }
    })
</script>

Separate Organisation Field + 3 Address lines

<!-- Postcode Field -->
<div id="postcode_lookup"></div>
<!-- Address Fields -->
<input id="organisation" type="text" placeholder="Organisation" />
<input id="line1" type="text" placeholder="Address Line 1" />
<input id="line2" type="text" placeholder="Address Line 2" />
<input id="line3" type="text" placeholder="Address Line 3" />
<input id="town" type="text" placeholder="Town" />
<input id="postcode" type="text" placeholder="Postcode" />
<!-- Add below form -->
<script>
    $('#postcode_lookup').getAddress({
        api_key: 'Enter-your-API-key',
        // Prevents the organisation from appearing within address line1
        line1_no_organisation: 'true',
        output_fields: {
            organisation: '#organisation',
            line1: '#line1',
            line2: '#line2',
            line3: '#line3',
            town: '#town',
            postcode: '#postcode',
        }
    })
</script>

Button Search

<!-- Postcode Field -->
<div id="postcode_lookup"></div>
<!-- Address Fields -->
<input id="line1" type="text" placeholder="Address" />
<input id="line2" type="text" placeholder="Address Line 2" />
<input id="line3" type="text" placeholder="Address Line 3" />
<input id="line4" type="text" placeholder="Address Line 4" />
<input id="town" type="text" placeholder="Town" />
<input id="postcode" type="text" placeholder="Postcode" />
<!-- Add below form -->
<script>
    $('#postcode_lookup').getAddress({
        api_key: 'Enter-your-API-key',
        // Will add a button to the postcode search field
        button: 'true',
        output_fields: {
            line1: '#line1',
            line2: '#line2',
            line3: '#line3',
            line4: '#line4',
            town: '#town',
            postcode: '#postcode',                        
        }
    })
</script>

Block Textarea

<!-- Postcode Field -->
<div id="postcode_lookup"></div>
<!-- Address Fields -->
<input id="organisation" type="text" placeholder="Organisation" />
<textarea id="address" placeholder="Address Line 1 etc."></textarea>
<!-- Add below form -->
<script>
    $('#postcode_lookup').getAddress({
        api_key: 'Enter-your-API-key',
        // Prevents the organisation from appearing within the textarea
        block_no_organisation: 'true',
        output_fields: {
            organisation: '#organisation',
            block: '#address'
        }
    })
</script>