API Overview

These documents describe the Autoaddress API, including authentication, HTTP resources and recommended best practices. This content is intended for individuals with web development experience and knowledge of HTTP.

The Autoaddress API uses:

  • HTTP GET
  • RESTful endpoint structure
  • Response payloads are formatted as JSON(P) 

API Endpoint

All API calls can be accessed from the following endpoint

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

Authentication

Each call to an Autoaddress REST API must be authenticated. This is done by passing the licence key (the key parameter in query string) to the request.

For a free developer key simply contact us


Security

Autoaddress REST API is accessible only using HTTPS secure protocol.


Responses

Returned as JSON(P) only.

Each response returns the appropriate HTTP Status Code based on the incoming request (See below for full list of HTTP Status Code returned). The exception is when JSONP is being used then the AutoAddress API will always response with HTTP 200 OK status codes, and pass the error data as part of the JSON response.


Same-origin Policy / JSONP

To solve the Same-origin policy restriction Autoaddress API supports JSONP requests. If you add a callback parameter then the response JSON will be wrapped in a JavaScript method that is named after value of mentioned callback parameter.


Comply with HTTP, URL, and JSON Specifications

We reserve the right to deny HTTP requests which are not fully compliant to our specifications. Use properly formed URLs and query strings, which includes URL-encoding query string parameters. Interpret all HTTP response payloads according to their Content-Type.

For example, application/json payloads should always be parsed as JSON. Our API produces valid JSON according to ECMA-404 standard, including whitespace between tokens. We are not responsible for problems resulting from handling JSON data improperly.


Enums

Enumerated types in response JSON are represented with an structure that has 2 properties:

  • Code – this is always an integer
  • Text – this is always a text
"addressType": {
  "code": 2150,
  "text": "ResidentialAddressPoint"
  }

HATEOAS Links

API response usually includes an array of HATEOAS links. This allows interaction with the API solely through the hyperlinks we provide you. You do not need to hardcode logic into your client in order to use our API.

"links": [
  {
    "rel": "next",
    "href": "https://api.autoaddress.ie/2.0/findaddress?key=...."
  }
]

The array of links can have many links, the link of interest must be identified using the value of the “rel” property (“next” in above example). .When the client identifies the link it should just follow the hyperlink 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.

Common values used for “rel” are:

  • next – follow this URL to comply with the recoomended API flow for real-tme capture
  • self – indicating the URL that created the current document

Response HTTP Status Codes

Code Summary Description
200 Success Everything worked as expected, search result is returned
400 Bad Request Invalid or Missing input parameter
401 Unauthorized Missing or Invalid User Key provided
404 Not Found Request URL does not exist.
429 Too Many Requests
The ​client has been rate limited, please wait a short while and retry the request again.
500 Error An error has occurred with Autoaddress.

Response Custom Error Codes

Code Description
400001 Invalid value for 'language' parameter.
400002 Invalid value for 'country' parameter.
400003 Invalid value for 'limit' parameter.
400004 Invalid value for 'addressId' parameter.
400005 Invalid value for 'ecadId' parameter.
400006 Invalid value for 'smartGroupingIndex' parameter.
400007 Missing value for required 'address' parameter.
400008 Invalid combination of given 'country' and 'language' parameters.
400009 Missing value for required 'postcode' parameter.
400010 Missing value for required 'ecadId' parameter.
401001 Missing value for required 'key' parameter (licence key).
401002 Invalid value for 'key' parameter (licence key).
401003 Licence key is disabled.
401004 Licence key expired.
401005 Access to restricted data.
404001 Requested resource was not found. Please check your URL.
500000 Internal server error.