Address Search/Lookup

Introduction

Implementing the AddressIT search/lookup functionality involves the following basic steps:

1. Provide a text field to capture the user's input.
2. As the user types more address details, send the input string to the AddressIT Lookup API function. See the Swagger Docs for more information on the Lookup function.
3. The lookup function will send back an array of address suggestions (as strings) which will be presented to the user as a clickable list.

End Result Example Screenshot

Here is how the address search text field and suggestions could look (from the AddressIT search demo):

Implementation

See below for code examples of a basic implementation of this, using JavaScript/React/Material-UI.

Search Input Field

Firstly, create an input field to handle the user input (note that TextField is a Material-UI component):

<TextField
    id="address-search-field"
    label="Address search"
    placeholder="Start typing an address"
    value={query}
    onChange={handleChange}
    onKeyDown={handleKeyDown}
    variant="outlined"
  />

Handle Input Changes

Write a function to handle the onChange event of the search text field (when the user types a character):

const handleChange = (event) => {
    const MIN_SEARCH_LENGTH = 4;
    const { value } = event.target;
    // don't search on spaces
    if (value.substring(value.length - 1) === " ") return; 
    if (value.length > MIN_SEARCH_LENGTH) {
      doSearch(value).then((results: string[]) => {
        setAddressSuggestions(
          results || []
        );
      });
    } else setAddressSuggestions([]);
  };

This takes the input, checks it's not empty and meets the requirement for minimum length, then passes it to the doSearch() function.

Do the Search/Lookup

Next, provide the doSearch() function to do the call to the AddressIT API Lookup function, using fetch and return the response data (address suggestions):

 const doSearch = async (search) => {
    if (!search) {
      throw new Error("Search string is required");
    }
    const encodedSearch = encodeURIComponent(search);
    const token = "<my_api_token>";
    const method = 'GET';
    const headers = {
      Authorization: `Bearer ${token}`,
    };
    const count = 5; 
    // the number of address suggestions returned 
    // by the lookup function
    const flags = 0;
    /**
      Flags are used to restrict the returned address suggestions 
      and is a combination of or'd bits.  
      0 - If flags is 0, no restriction is set and find both street 
      and postal addresses in both the Australia Post PAF and GNAF databases. 
      If flags includes:
      1 - find street addresses.
      2 - find postal addresses.
      With neither 1 or 2, the default is to find both street and postal addresses.
      If flags includes:
      4 - find AusPost PAF addresses (don't return addresses only found in the GNAF).
      8 - find GNAF addresses (don't return addresses only found in the PAF).
      With neither 4 or 8, the default is to find both PAF and GNAF addresses.
    **/

    return fetch(`https://api.addressit.isw.net.au/lookup?search=${encodedSearch}
    &count=${count}&flags=${flags}`, {
      headers,
      method,
    })
    .then((response) => {
      return response.json().then((data) => {
        const { ok, status, statusText } = response;
        if (!ok) {
          return Promise.reject({
            message: data.message || data.errmsg || data.name,
            status,
            statusText,
            data,
          });
        }
        return data;
      });
    }) 
    .catch((err) => {
      console.log("Fetch error", err);
      return Promise.reject(err);
    });
  };

Present Suggestions in a List

Now that we have the address suggestions as a response back from the Lookup API call, we need to present these as selectable options in a list below the search input field.

In the case of this React/Material-UI example, the suggestions are shown in a "Popper" component, which is just a way of displaying the listed address suggestions as a floating box that is anchored below the search input field. The array of address suggestions are mapped to list items. The address suggestions are split up into 3 address lines (by calling a split() on the string using the new line character as the delimiter) with address line 1 as the primary text, and line 2 and 3 as the secondary text shown underneath.

  <Popper
    id="address-search-suggestions"
    open={!!addressSuggestions && addressSuggestions.length > 0}
    anchorEl={searchInputField}
    placement="bottom-start"
  >
    <List>
      {addressSuggestions?.map((suggestion, index) => {
        const [addressLine1, addressLine2, addressLine3] =
          suggestion!.split(/\r?\n/);
        return (
          <ListItemButton
            key={suggestion}
            selected={selectedAddressIndex === index}
            onClick={() => {
              select(suggestion);
            }}
          >
            <ListItemIcon>
              <PlaceIcon />
            </ListItemIcon>
            <ListItemText
              primary={addressLine1}
              secondary={`${addressLine2} ${addressLine3}`}
            />
          </ListItemButton>
        );
      })}
    </List>
  </Popper>

Next Step - Process Selected Address

Once the user finds their address in the list, clicking on it should initiate a call to the AddressIT Process API function. The address string the user clicked on is sent to Process, which then returns a fully matched address, parsed into its separate address components.

See the next step, Process Address for more detail.

Also, see Parse Address for information on how to handle the situation where a user can't find their address in the address suggestions returned by the Lookup function.