documentation

Quick Integration (UI / Forms)

Table of Contents

Easy way to add postcode lookup to your HTML address form.

Please embed the latest version of the JavaScript class from cdn.

“We recommend you use our CDN version to ensure you always have the latest functionality and security”

CDN address: https://assets.postcodex.io/postcodex-api.min.js

Add the js lib #

Create/open your HTML file and add the postcodex-api.min.js include from our CDN :

<script src="https://assets.postcodex.io/postcodex-api.min.js"></script>

create the html code #

Create an address form:

<div>
    Postcode:<br/>
    <input type="text" name="postcode" id="postcode"/>&nbsp;&nbsp;&nbsp;
    <button type="button" onclick="pcx.postcodeLookup.handle()">Find Address</button><br/>
    <div name="postcode_list_display" id="postcode_list_display">&nbsp;</div><br/>
    Company:<br/>
    <input type="text" name="companyname" id="companyname"/><br/>
    Address:<br/>
    <input type="text" name="addressline1" id="addressline1"/><br/>
    <input type="text" name="addressline2" id="addressline2"/><br/>
    <input type="text" name="addressline3" id="addressline3"/><br/>
    Town:<br/>
    <input type="text" name="town" id="town"/><br/>
</div>

wire the form to js class #

Instantiate and setup the js class

The following example uses the ‘Find Adddress’ button onclick to call the lookup action

var pcx = new PostcodexApi({  
    token: "{insert your token here}",
    postcodeLookupOptions: {  
        pcx_output             : "postcode_list_display",  
        pcx_input              : "postcode",  
        pcx_organisationname   : "companyname",  
        pcx_addressline1       : "addressline1",  
        pcx_addressline2       : "addressline2",  
        pcx_addressline3       : "addressline3",  
        pcx_posttown           : "town",  
        selector_type          : "id"
    }  
});

The lookup result will be placed into the ‘postcode_list_display’ element, either the address list or an error message.

alternative configurations #

The following configuration discards the onclick setting from the ‘Find Address’ button

This html form use the default ids for each field

<div>
    Postcode:<br/>
    <input type="text" id="pcx_input"/>&nbsp;&nbsp;&nbsp;
    <button type="button" id="pc_lookup">Find Address</button><br/>
    <div id="pcx_output">&nbsp;</div><br/>
    Company:<br/>
    <input type="text" id="pcx_organisationname"/><br/>
    Address:<br/>
    <input type="text" id="pcx_addressline1"/><br/>
    <input type="text" id="pcx_addressline2"/><br/>
    <input type="text" id="pcx_addressline3"/><br/>
    Town:<br/>
    <input type="text" id="pcx_posttown"/><br/>
</div>

This way the js configuration only needs to set the token, and identify the search button

var pcx = new PostcodexApi({
    token: "{insert your token here}"
})
pcx.postcodeLookup.wire({
    button: "#pc_lookup"
})
// pcx.postcodeLookup("wire", {
//     button: "#pc_lookup"
// })

Full html example #

The following code is a full html page that creates a postcode form and wires it to postcodex api.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
  <title>Postcodex Search Example</title>
  <script src="https://assets.postcodex.io/postcodex-api.min.js"></script>
  <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css">
</head>
<body>
<div class="container">
  <div class="row">
    <div class="col-xs-12 col-lg-6 col-lg-offset-3">
      <h3 id="title" style="text-align: center;">Postcodex Search Example</h3>
    </div>
    <hr />
  </div>
  <div class="row" name="pcx_form" id="pcx_form">
    <div class="col-12 col-lg-6 offset-lg-3">
      <div style="width: 100%">
        Postcode:<br/>
        <input type="text" id="postcode"/>
        <button type="button" id="pc_lookup">Find Address</button><br/>
        <span id="postcode_list_display"></span><br/>
        Company:<br/>
        <input type="text" id="companyname"/><br/>
        Address:<br/>
        <input type="text" id="address1"/><br/>
        <input type="text" id="address2"/><br/>
        <input type="text" id="address3"/><br/>
        Town:<br/>
        <input type="text" id="town"/><br/>
      </div>
    </div>
  </div>
</div>
<script>
  var pcx = PostcodexApi.factory({
    token: '{insert your token here}',
    postcodeLookupOptions: {}
  });
  pcx.postcodeLookup('wire', {
    button                : 'pc_lookup',
    pcx_output            : "postcode_list_display",
    pcx_input             : 'postcode',
    pcx_organisationname  : 'companyname',
    pcx_addressline1      : "address1",
    pcx_addressline2      : "address2",
    pcx_addressline3      : "address3",
    pcx_posttown          : "town"
  })
</script>
</body>
</html>