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.

Result Code Result Description User Message
100 Postcode Appended Address Found
110 Postcode Validated Address Found
120 Postcode Amended Postcode amended to match Address
130 Address Amended to Match Postcode Address amended to match Postcode
140 Postcode and Address Amended Address and Postcode amended
150 Postcode Not Validated Postcode used, address insufficient
200 Postcode Not Available Address Found. No Postcode available for this address

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.

Result Code Result Description User Message
300 Non-Unique Address Address found, please enter your postcode below if you know it.
400 Partial Address Match Address not found, please enter your postcode below if you know it.
500 Incomplete Address Entered Incomplete address. Please enter your complete address and postcode below.
Alert Scenarios
An Alert Scenario is where there is an issue with the address.
Result Code Result Description User Message
210 Postcode Retired Postcode Address no longer exits
550 No Address Match Address not found, please enter full address below.
600 Foreign Address Detected {Logic for handling addresses outside your supported Country}
700 Invalid Address Entered Invalid address.  Please enter your full address below.

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: