Other#

Best Practices #

Matching Addresses #

Not every address will be found in Express Entry. For example, new addresses and rural addresses not serviced by the United States Postal Service may not be available. Your code should allow for the case that Express Entry does not have the submitted address and handle it appropriately. For example, you may require in your code that if the address comes up with ‘no results found’, then force the user to fill out the full address with all of line 1, city, state, and ZIP Code – and only then be able to move forward with the application. More addresses will be added in future versions including new and rural addresses.

When to Address Check #

A Best Practice is to send the address through an address checker, such as Address Object, if it does not come up in Express Entry. Verifying the address using Address Object or WebSmart Web Service after attempting a match is useful in those cases that the user is required to type the whole address, since the address is unverified in this case. Also, users should know that when there is only one address showing in the results window, and this is the match, then there is no need to type further since they may choose this address with the mouse (or keyboard, depending on the implementation).

‘Official’ City Name #

In the fielded query, (which uses the ExpressPostalCode service), where multiple city names are offered, choose only the ‘official’ city name. Abbreviated cities may not contain thoroughfare names.

Sample Code Fields #

In the sample code, all that is needed to access the fields that are populated by the service is the field name. Once the data entry user selects a choice from the listbox, the information is ready to place into variables.

Tab Stops #

The sample code (VB and C#) tab stops are set in the form so that the user can use the keyboard without the mouse to use the service.

Updates #

Check the product page on the Melissa Data Wiki (Express Entry) for an update on bugs and features that may be added.

Fielded Search #

In the Fielded Search example in the sample code, it is not necessary to pass the city name. In fact, passing the city name restricts the system to returning results only within that city. The ZIP Code is sufficient to find the address within the system in this case.

Free Form City #

In Free Form Entry, only the official U.S. Postal Service deliverable city names show up in a given ZIP code. This means that when entering an address, you may be given a city different than your expected city. Because of the way standardization is for addresses within the United States Postal Service and the data, the address that Express Entry returns is actually the official deliverable city for that ZIP code. Deliverability is not affected by the city being different than expected in this case.

User Address Search #

The data entry user can ‘search’ for an address using backspace and entering different characters in the search box. The service supports this feature. Add characters to narrow the search, take away characters to broaden the search.

Encoding with Internet Explorer #

Internet Explorer does not UTF-8 encode characters with accents and other diacritics (such as à to %c3%a0) when sending them, so to query the service with Internet Explorer, one must manually enter their encodings.

U.K. Free Form Address Lookup Sample Code #

U.K. Free Form Address lookup was created from the sample code below.

Introduction #

Adding Global Express Entry’s Free Form lookup to your web page is simple when you use the sample code provided. For the most part, you just need to copy and paste the autocomplete function targeting the input field, make a few modifications, and suit to taste. The autocomplete function itself is JQuery code that resides in between <script> tags and is associated with your input field. This guide will show you how to take the sample code and add it to a basic web page.

<script> Section #

First let’s take a look at the sample code:

jQuery(document).ready(function()
  {
    $('#address1').autocomplete(
    {
      showHeader: true,
      minLength: 4,
      delay: 400,
      source: function(request, response)
      {
        $.getJSON(url + "jsonp/GlobalExpressFreeForm?callback=?", {format: "jsonp", id: id, FF: request.term, country: $('#country').val(), maxrecords: "10"}, function (data)
        {
          //alert(JSON.stringify(data.Results));
          response($.map(data.Results, function( item )
          {
            return{label: item.Address.DeliveryAddress + ", " + item.Address.Locality + ", " + item.Address.AdministrativeArea + ", " + item.Address.PostalCode, value: item.Address.DeliveryAddress};
          }));
        });
      },
        select: function(evt, ui)
        {
          //put selection in result box
          this.form.result.value = ui.item.label;
        }
      });
  });

As you can see, the autocomplete function is bound to the HTML element ‘address1,’ which will start autocompleting after 4 keystrokes, with a delay of 400 milliseconds.

Next the source is defined with its request object and response callback (you don’t need to know the meaning of those terms to use Express Entry, so we’ll skip a discussion of object-oriented programming and callbacks here). Here you will need to do a little editing.

getJSON #

The following code points to the server and the web service:

$.getJSON(url + "jsonp/GlobalExpressFreeForm?callback=?", {format: "jsonp", id: id, FF: request.term, country: $('#country').val(), maxrecords: "10"}, function (data)
  {
    //alert(JSON.stringify(data.Results));
    response($.map(data.Results, function( item )
    {
      return{label: item.Address.DeliveryAddress + ", " + item.Address.Locality + ", " + item.Address.AdministrativeArea + ", " + item.Address.PostalCode, value: item.Address.DeliveryAddress};
    }));
  });
},

The label: and value: inside the return statement control how the pick list will look and what the output will be like when an item on it is selected.

select:function #

Next is the select parameter of autocomplete(), which controls what will happen when one of the items on the pick list is selected:

select: function(evt, ui)
  {
    //put selection in result box
    this.form.result.value = ui.item.label;
  }

The label from the previous section of code will be placed into the item with id ‘result,’ in the HTML form on this page. We’ll change this section to suit our needs later.

And that explains the <script> section of the code, which we will now modify to work with the demo HTML page.

<html> Section #

Moving on to the web page, we set up the <html> and <head> sections:

<html>
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie-edge">
<title>U.K. Address & Postcode Lookup</title><br>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="main.css" />
<script src="http://code.jquery.com/jquery-1.8.2.js"></script>
<script src="http://code.jquery.com/ui/1.9.1/jquery-ui.js"></script>
<link rel="stylesheet" href="http://code.jquery.com/ui/1.9.1/themes/base/jquery-ui.css" />

This section is basically just some metadata, a title, and the necessary includes for JQuery from the Content Delivery Network.

<script>#

Next set up the <script> section:

<script>
var id;
id='#########';
url = "https://expressentry.melissadata.net/";

Put your ident or License Key into the id variable instead of ‘#########’. Set the variable, (in this case ‘id’), to your License Key given to you by Melissa Data so it can be passed with each request. Now let’s put an imaginary bookmark in the JavaScript code here so we can come back later when the HTML is finished.

<body>#

Set up the <body> section of the HTML:

<body>
<form>
<div class="container">
  <div class="subHead"><h3>Free Form Address Lookup &nbsp&nbsp <a href="http://wiki.melissadata.com" style="color:white">(How we created this lookup from the sample code)</a></h3></div>
  <div class="padded">
  <p class="intro">Enter Address:    <br></p>
  <input id="freeform" type="text" style="padding:2px;width:600px;"></input><br><br>
    <div id="organizationout">Organization</div>
    <div id="buildingnameout">Building Name/SubBuilding</div>
    <div id="buildingnumberandthoroughfareout">Building Number and Thoroughfare</div>
    <div id="localityout">Local Area or Village Name</div>
    <div id="posttownout">Post Town</div>
    <div id="postcodeout">Postcode</div><br>
    <input id="clear" type="button" name="Query" value="Clear" class="btn" />
  </div>
</div>
</form>
</body>

The main point of interest here is the <input> line. Its id, ‘freeform’, is used as a hook for the autocompletion code. The <div>’s will act as destinations for the autocomplete. In the case of the country UK, those fields are: Organization, Building & Subbuilding, Building Number & Thoroughfare, Local Area or Village Name, Post Town, and Postcode, according to the standard addressing format from Royal Mail for the United Kingdom.

jQuery #

Back to the mental bookmark. Since we have the HTML all ready for the viewable portion of the web page, we can now set up the JavaScript. Copy and paste this section from the sample code continuing the <script> section:

jQuery(document).ready(function()
  {
    $("#freeform").focus();
      $('#freeform').autocomplete(
      {
        showHeader: false,
        minLength: 4,
        delay: 400,
        source: function(request, response)
        {
          $.getJSON(url + "jsonp/GlobalExpressFreeForm?callback=?", {format: "jsonp", id: id, FF: request.term, maxrecords: "50", country: "GB"}, function (data)
          {
             //alert(JSON.stringify(data.Results));
             response($.map(data.Results, function( item )

A few things to do here; add the target ‘#freeform’ in the beginning to place the focus on the input field when the page loads, add the target $(‘#freeform’).autocomplete so the browser knows that the input field is an autocompleting one, and replace the country parameter with ‘GB’ since that is the only country we will be using for this web page.

label and value #

For the next part it is important to know that certain lines in U.K. Addresses are not always necessary, for example Organization, but since we sometimes have them in the data, I use the ternary operator to make the Organization field appear or disappear when desired.

{
  return{
    label: item.Address.Organization == '' ? (item.Address.DeliveryAddress + ", "  + item.Address.Locality + ", " + item.Address.AdministrativeArea + ", " + item.Address.PostalCode) : (item.Address.Organization + ", " + item.Address.DeliveryAddress + ", "  + item.Address.Locality + ", " + item.Address.AdministrativeArea + ", " + item.Address.PostalCode),

    value: item.Address.PostalCode, organization: item.Address.Organization, buildingname: item.Address.Building, subbuilding:  item.Address.SubBuilding, buildingnumberandthoroughfare: item.Address.Premise + " " + item.Address.Thoroughfare, locality: item.Address.DependentLocality, posttown: item.Address.Locality, postcode:  item.Address.PostalCode
  };

select:function(2)#

Almost done: we use the select parameter, again with the ternary operator, to fill out the sections which we laid out in the div’s in HTML (Watch for closing braces and parentheses here):

}));
  });
    },
      select: function(evt, ui)
      {
        $("#organizationout2").text ( ( ui.item.organization == '' ) ?  ( "" ) : ( ui.item.organization ) );
        $("#buildingnameout2").html ( ( ui.item.buildingname == '' ) ? (
          ui.item.subbuilding == '' ? "" :  ui.item.subbuilding ) : ( ui.item.buildingname + "<br/>" + ui.item.subbuilding ) );
        $("#buildingnumberandthoroughfareout2").text ( ui.item.buildingnumberandthoroughfare );
        $("#localityout2").text ( (ui.item.locality == '' ) ?  ( "" ) : ( ui.item.locality ) );
        $("#posttownout2").text ( ui.item.posttown.toUpperCase() );
        $("#postcodeout2").text ( ui.item.postcode );
      }
    });

clear Button #

Finally a little code for the clear button:

$('#clear').click(function()
  {
    //clear form
    //with a reload
    //window.location.reload(true);
    //or just clear the fields
    this.form.freeform.value = '';
    $("#organizationout").text ("Organization");
    $("#buildingnameout").text ("Building Name/SubBuilding");
    $("#buildingnumberandthoroughfareout").text ("Building Number and Thoroughfare") ;
    $("#localityout").text ("Local Area or Village Name") ;
    $("#posttownout").text ("Post Town") ;
    $("#postcodeout").text ("Postcode");
    //set focus
    $("#postcode").focus();
  });
});

And don’t forget to close with the </script> tag in its location above <body> and <form>:

</script>

This web page, as shown in the includes at the top, will also require the main.css file to be in the same directory. That’s how the lookup page was created. If you followed this guide you should now have a web page which will access Melissa Data’s web service to autocomplete addresses in the U.K., filling out the HTML form according to Royal mail’s standard addressing guidelines.

Other

Contents

Other#