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 license key (the  key the parameter in the query string) to the request. 

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 a full list of HTTP Status Code returned). The exception is when JSONP is being used, the AutoAddress API will always respond 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 call-back parameter, then the response JSON will be wrapped in a JavaScript method that is named after the value of the mentioned call-back parameter.

Comply with HTTP, URL, and JSON Specifications

We reserve the right to deny HTTP requests which are not fully compliant with our specifications. Use properly formed URLs and query strings, which include 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 standards, including whitespace between tokens. We are not responsible for problems resulting from mishandling JSON data.

Enums

Enumerated types in response JSON are represented with a 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 to use our API.

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