National Pest Management
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    jquery-postcodespublic

    UK Postcode Lookup jQuery Plugin

    Add UK address lookups with a simple postcode input field on any web form with the Ideal-Postcodes.co.uk API. Ideal Postcodes uses Royal Mail's addressing database, the Postcode Address File (PAF).

    Build Status Sauce Test Status Sauce Test Status

    PAF is licensed from the Royal Mail and incurs a license fee per lookup. We make PAF available to the public at 2p per external lookup.

    How it Works

    This plugin creates an input field to lookup postcodes on the Ideal Postcodes API. If your user searches a valid postcode, a dropdown menu is displayed and the selected address is piped into appropriate fields.

    The plugin provides addresses according to Royal Mail's Addressing Guidelines. This consists of 3 address lines, a Post Town and Postcode and is sufficient to uniquely identify a premise in the UK.

    Ideal Postcodes Plugin Example

    Getting Started

    1. Download the plugin and add to your page
    <script src="jquery.js"></script>
    <script src="jquery.postcodes.min.js"></script>
    1. Sign up to get an API key

    2. Setup a Postcode Search Field by inserting an empty div tag and calling .setupPostcodeLookup(). Pass in a configuration object identifying specifying your API Key and address fields (using CSS selectors)

    <div id="postcode_lookup_field"></div>
    <script>
    $('#postcode_lookup_field').setupPostcodeLookup({
        // Set your API key
        api_key: 'iddqd',
        // Pass in CSS selectors pointing to your input fields to pipe the results
        output_fields: {
            line_1: '#first_line',
            line_2: '#second_line',
            line_3: '#third_line',
            post_town: '#post_town',
            postcode: '#postcode'
        }
    });
    </script> 

    Documentation & Configuration

    Latest documentation can be found at ideal-postcodes.co.uk

    This plugin also allows you to draw additional addressing information. The complete list of available data fields can be found here.

    There are a lot of ways to configure the plugin to create an address lookup feature that suits most use cases. The documentation will guide you through how to use additional configuration options like customised styling, customised inputs & triggers, useful callbacks, key checking, etc.

    For examples of the more advanced ways you can configure the plugin take a look at ideal-postcodes.co.uk/jquery.

    Testing

    Run automated tests with

    grunt test
    

    Please use jQuery 1.9.x or higher. This plugin has been tested against jQuery 1.9.x, 1.10.x, 1.11.x, 2.0.x, 2.1.x, 2.2.x, 3.0.x. 3.1.x and 3.2.x

    You may run the plugin locally and test in your browser

    $ npm start # starts a HTTP server 
     
    # Navigate to the `examples` folder and select an example in a *.html file 

    Our test postcodes are:

    • ID1 1QD Returns a successful postcode lookup response (2000)
    • ID1 KFA Returns "postcode not found" error (4040)
    • ID1 CLIP Returns "no lookups remaining" error (4020)
    • ID1 CHOP Returns "daily (or individual) lookup limit breached" error (4021)

    License

    MIT

    install

    npm i jquery-postcodes

    Downloadsweekly downloads

    88

    version

    3.0.7

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar