API Flow

Autoaddress API Flow Explained

The purpose of this page is to explain the flow of the Autoaddress 2.0 API in a real-time address capture implementation.

NOTE: If you are currently a user of our jQuery Plugin, most of the logic below is already built in and you only need to handle the onAddressFound (data) event when it has been fired.

The main API call is FindAddress, which you call when a user enters a partial address and searches, or the user chooses an option returned by the Autocomplete API call.

The FindAddress API call response will either contain Options or indicate that a Result has been reached. The Options consist of an array of HATEOAS links. This allows interaction with the API solely through the hyperlinks we provide you. As a developer you display the options to the user as a list. When the user selects an Option, retrieve the next href from that Option object and perform a GET request on that URL which will make the next FindAddress call. Repeat until no Options are returned, and we've reached a Result.

When the FindAddress API call response contains no Options, this indicates the API has a final answer for the user's address search. At this point you need to check the  Result of the address query. You may also choose to get additional data at this point (e.g., Latitude, Longitude) by calling GetEcadData or GetGBPostcodeData.

Options

To check for Options in the response check  options.length. There is also a property called totalOptions which is usually the same value as  options.length but will sometimes contain a value even though options.length=0. This indicates that there were too many options to return.

Below you will see what the Options object looks like, the key property here is the  next link in the links array which contains all the details prepared for you to continue the search if the user chooses this option.

"options": [
        {
            "optionType": {
                "code": 0,
                "text": "Standard"
            },
            "displayName": "4 INNS COURT, WINETAVERN STREET, DUBLIN 8",
            "addressId": 1702105351,
            "addressType": {
                "code": 2100,
                "text": "NonResidentialAddressPoint"
            },
            "links": [
                {
                    "rel": "next",
                    "href": "https://api.autoaddress.ie/2.0/findaddress?key=YOUR_KEY&txn=83de3926-45e5-40fb-a8c9-3b8eb0fec06d&address=4%20inns%20court&addressId=1702105351&limit=-1"
                }
            ]
        },

Result

The end of the flow for the FindAddress API is when the response does not include any more options, this indicates the API has a final answer for the user's query. At this point you need to check the  Result code returned by the FindAddress API call.

Tip: If your response has options, it will still contain a  Result object, but in this scenario, it is not that important. You should just display the options and let the user continue the search by clicking on the options.

"result": {
    "code": 100,
    "text": "PostcodeAppended"
  }

The codes can be used to categorise the result into three categories Success, Warning and Alert.

Success Scenarios

A success scenario returns a Postcode. The following Result codes return a Postcode, together with a potential message to display to the user.

N.B. In the case of 150 we haven't been able to match the input address sufficiently to determine it definitely matches the Postcode. Rather than throw the Postcode away, we throw away the input address, and return the full address for the Postcode.

Warning Scenarios

A Warning Scenario is where the address has been partially or fully matched but has not returned a Postcode. The User should be asked to enter their Postcode if they know it.

Alert Scenarios

Next steps

Congrats! You’ve gone through the basic flow of real-time address capture in our Autoaddress API. Some things you might want to read next:

• 1. How well has the address matched?
• 2. Example addresses to test your API implementation