Find Address

Lookup a Postcode or Address. Returns all available data if found.

Please read API Overview first

API Endpoint

The Find Address API endpoint is 

https://api.autoaddress.ie/2.0/FindAddress

N.B. This EndPoint URL resolves to a dynamic IP address, please be aware of this when making DNS and Firewall decisions.

Request

To search for a Postcode or Address, a simple  GET request from your desired language is all that is needed.

  • cURL
curl -v "https://api.autoaddress.ie/2.0/FindAddress?key=YOUR_KEY&address=YOUR_ADDRESS_OR_POSTCODE&vanityMode=true&addressProfileName=Demo5LineV2"
  • jQuery
$.ajax({
   type: "GET",
   dataType: "jsonp",
   url: "https://api.autoaddress.ie/2.0/FindAddress",
   data : {
       key: "YOUR_KEY",
       address: "YOUR_ADDRESS_OR_POSTCODE",       addressProfileName: "Demo5LineV2",       vanityMode: "true"
   },
   success: function(data){
       //do something with data
   }
});
  • Angular JS
$http.jsonp('https://api.autoaddress.ie/2.0/FindAddress',{
   params: {
      key: "YOUR_KEY",
      address: "YOUR_ADDRESS_OR_POSTCODE",      addressProfileName: "Demo5LineV2",      vanityMode: "true"
   }
}).success(function(data){
   //do something with data
});
  • Ruby
require 'json'
require 'net/http'

uri = URI.parse("https://api.autoaddress.ie/2.0/FindAddress?key=YOUR_KEY&address=YOUR_ADDRESS_OR_POSTCODE&addressProfileName=Demo5LineV2&vanityMode=true")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
response = http.get(uri.request_uri)
result = JSON.parse(response.body)
  • Python
import json
import urllib2
 
Response = urllib2.urlopen ("https://api.autoaddress.ie/2.0/FindAddress?key=YOUR_KEY&address=YOUR_ADDRESS_OR_POSTCODE&vanityMode=true&addressProfileName=Demo5LineV2")
jsonResult = json.load(Response)
  • C#
using System.IO;
using System.Net;

HttpWebRequest request = (HttpWebRequest)WebRequest.Create("https://api.autoaddress.ie/2.0/FindAddress?key=YOUR_KEY&address=YOUR_ADDRESS_OR_POSTCODE&vanityMode=true&addressProfileName=Demo5LineV2");
request.Method = WebRequestMethods.Http.Get;
request.Accept = "application/json";

using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
{
   var result = new StreamReader(response.GetResponseStream()).ReadToEnd();
}

Response

The following is a sample JSON response returned for a Find Address API request. 

{ 
     "result": 
     { "code": 100,
       "text": "PostcodeAppended" 
     }, 
     "isUniqueAddress": true, 
     "postcode": "A96E2R8", 
     "addressId": 1702008318, 
     "addressType": 
     { 
          "code": 2150, 
          "text": "ResidentialAddressPoint" 
     }, 
     "matchLevel": 
     { 
          "code": 2, 
          "text": "AddressPoint" 
     }, 
     "postalAddress": [ 
          "1 WOODLANDS ROAD", 
          "GLENAGEARY", 
          "CO. DUBLIN" 
     ],
     "vanityAddress": [ 
          "1 Woodlands Road", 
          "Dun Laoghaire", 
          "Co. Dublin" 
     ], 
     "reformattedAddressResult": 
     { 
          "code": 100, 
          "text": "Success" 
     }, 
     "reformattedAddress": [ 
          "1 Woodlands Road", 
          null, 
          null, 
          "Dun Laoghaire", 
          "Co. Dublin" 
     ],
     "cleanResult": 
     { 
          "isSpellingChanged": false, 
          "isFormatChanged": false, 
          "isAltered": false 
     }, 
     "totalOptions": 0, 
     "options": [], 
     "input": 
     { 
          "key": "YOUR_KEY", 
          "txn": "cfb4b366-0653-41a2-86b4-0562332ee4c4", 
          "address": "1 WOODLANDS ROAD, DUN LAOGHAIRE, CO. DUBLIN", 
          "addressId": 1702008318, 
          "language": "en", 
          "country": "ie", 
          "limit": -1, 
          "geographicAddress": false, 
          "vanityMode": true, 
          "addressElements": false,
          "addressProfileName": "Demo5LineV2",
          "links": [ 
             { "rel": "self",
               "href": "https://api.autoaddress.ie/2.0/findaddress?key=YOUR_KEY&txn=cfb4b366-0653-41a2-86b4-0562332ee4c4&address=1%20Woodlands%20Road,%20Dun%20Laoghaire,%20Co.%20Dublin&addressId=1702008318&limit=-1&geographicAddress=False&vanityMode=True&addressProfileName=Demo5LineV2&addressElements=False             } 
          ]
     } 
}

 

Input Fields

Name Type Default Description
key* string None Licence key
IMPORTANT: The key parameter name must be all lower case.
address* string None Address or Postcode to Search
addressId integer None ID of the Address to search. (i.e. ECAD ID for Ireland)
limit integer -1 An upper limit on the number of options that may be returned. The default value is -1. Having the limit set to -1 allows for intelligent grouping when many address options are returned.
language string "en" Language for returned address. Allowed values are "en" for English and "ga" for Irish.
country string "ie" Country the address should be searched in. Allowed values are "ie" for Ireland, "ni" for Northern Ireland and "gb" for Great Britain.
geographicAddress boolean false Return geographic address.
vanityMode boolean false Return vanity address format, if it exists.
addressElements boolean false Return address elements.
addressProfileName string None If supplied, a reformatted address (according to profile rules) is returned in reformattedAddress field in JSON response.
txn string None Transaction ID from previous call in the session

* Required Field

Output Fields

Name Type Description
result enum Result of the search
  • PostcodeAppended = 100
  • PostcodeValidated = 110
  • PostcodeAmended = 120
  • AddressAmendedToMatchPostcode = 130
  • PostcodeAndAddressAmended = 140
  • PostcodeNotValidated = 150
  • PostcodeNotAvailable = 200
  • PostcodeRetired = 210
  • NonUniqueAddress = 300
  • PartialAddressMatch = 400
  • IncompleteAddressEntered = 500
  • NoAddressMatch = 550
  • ForeignAddressDetected = 600
  • InvalidAddressEntered = 700
postcodeNotAvailable enum Reson why result equals PostcodeNotAvailable. Not present if result equals any other value.
  • NoMailDelivery= 1
  • NoRoutingKey= 2
  • NoCoordinates= 3
isUniqueAddress boolean Flag to denote whether the address is unique
postcode string Eircode or Postcode
addressId integer Address ID (i.e., ECAD ID for Ireland)
addressType enum Type of Address Found Full list of Address Types
matchLevel enum Match Level for the Address Found
  • NoMatch = 0
  • SubAddressPoint = 1
  • AddressPoint = 2
  • Organisation = 3
  • Building = 4
  • BuildingGroup = 5
  • Thoroughfare = 6
  • Locality = 7
  • PostTown = 8
  • County = 9
unmatched string [ ] Part of the input address that could not be matched
unmatchedAddressElements addressElement [ ] Address elements for the part of the input address that could not be matched
postalAddress string [ ] Postal address in requested language for the input address
postalAddressElements addressElement [ ] Postal address elements in requested language for the input address
geographicAddress string [ ] Geographic address in requested language for the input address
geographicAddressElements addressElement [ ] Geographic address elements in requested language for the input address
vanityAddress string [ ] Vanity address in case it was requested per input and it is available.
vanityAddressElements addressElement [ ] Vanity address elements in case it was requested per input and it is available.
reformattedAddress string [ ] Address that was reformatted in case addressProfileName was supplied in input fields.
reformattedAddressResult enum Reformatted address result
  • Success = 100
  • AddressElementTruncated = 101
  • AddressElementLost = 102
  • AddressElementLostAndTruncated = 103
  • AddressElementAbbreviated = 110
cleanResult CleanResult Describes how the output has changed from the input.
totalOptions integer Total number of options. This value is always 0 if the value of input field limit is 0. If this value is greater than the value of input field limit then no options are returned.
options option [ ] An array of Option objects (described below).
input object Input object with request input fields.
links link [ ] An array of Link objects (described below).
AddressElement Object
Name Type Description
value string The value of the address element
type enum Type of the address element
  • Unknown = 0
  • Organisation = 1
  • AddressPointName = 2
  • BuildingName = 3
  • BuildingNumber = 4
  • BuildingGroup = 5
  • Thoroughfare= 6
  • Locality = 7
  • Village = 8
  • Town = 9
  • PostTown = 10
  • City = 11
  • DublinPostalArea = 12
  • County = 13
  • Eircode = 14
  • UrbanArea = 16
  • RuralLocality = 17
addressId integer Address ID (i.e., ECAD ID for Ireland)
CleanResult Object
Name Type Description
IsSpellingChanged boolean This property is true when the result has a spelling difference compared to the input. A spelling change includes:
  • Input word is misspelled 
  • Input word is equal to two output words in the same element and vice versa
IsFormatChanged boolean This property is true when the result has a format difference compared to the input. A format difference includes:
  • Rearranged words
  • Input contains empty elements
  • Input contains duplicate elements
  • Input contains hyphens and output does not
  • Output contains hyphens and input does not
  • Input contains county element without including "CO."
  • One input element is equal to multiple output lines and vice versa
  • Input contains abbreviations
IsAltered boolean This property is true when the result has been altered compared to the input. An alteration includes:
  • Input element has been removed in output
  • Output contains extra elements not present in the input
  • Words present in an input element not present in the same output element and vice versa
  • Input has different Dublin area number to output
  • Input county is different to output county
Option Object
Name Type Nullable? Description
optionType enum No Option Type Details
  • Standard = 0
  • GroupedNonBusiness = 1
  • GroupedBusiness = 2
displayName string No Option Name
postcode string Yes Eircode or postcode
addressId integer Yes Address ID (i.e., ECAD ID for Ireland).
addressType enum Yes Type of Address Found Full list of Address Types
links link [ ] No An array of Link objects (described below).
Link Object
Name Type Description
rel string API response usually includes an array of HATEOAS links. This allows interaction with the API solely through the hyperlinks we provide you. You no longer need to hardcode logic into your client in order to use our API.
href string The hyperlink the client should follow is stored in the value of “href” property. That value can have some internal parameters, so the client should not parse it or modify it in any way.