Other/API Reference - Ideal Postcodes

Lookup Postcode

v1.0.0

Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive.

The Postcode Lookup API provides a JSON interface to search UK addresses from a postcode. It can be used to power Postcode Lookup driven address searches, like .

Postcode Not Found

Lookup balance is unaffected by invalid postcodes. The API returns a 404 response with response body:

Suggestions

If a postcode cannot be found, the API will provide up to 5 closest matching postcodes. Common errors will be corrected first (e.g. mixing up O and 0 or I and 1).

If the suggestion list is small (fewer than 3), there is a high probability the correct postcode is there. You may notify the user or immediately trigger new searches.

The suggestion list will be empty if the postcode has deviated too far from a valid postcode format.

Multiple Residence

A small number of postcodes will return more than 100 premises. These may require pagination. Use page to paginate the result set.

Input

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "description": "Comma separated whitelist of address elements to return. \n\nE.g. `filter=line_1,line_2,line_3` returns only `line_1`, `line_2` and `line_3` address elements in your response\n"
    },
    "page": {
      "type": "integer",
      "format": "int32",
      "description": "0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0. \n\nA small number of Multiple Residence postcodes may need pagination (i.e. have more than 100 premises).\n"
    },
    "postcode": {
      "type": "string",
      "description": "Correctly formatted postcode. Capitalised and spaced."
    }
  },
  "required": [
    "postcode"
  ],
  "additionalProperties": false
}

Output

{
  "type": "object",
  "required": [
    "code",
    "message",
    "result"
  ],
  "properties": {
    "code": {
      "type": "integer",
      "format": "int32",
      "enum": [
        2000
      ]
    },
    "message": {
      "type": "string",
      "enum": [
        "Success"
      ]
    },
    "result": {
      "type": "array",
      "description": "All addresses listed at the postcode.\n\nIf Eircode is enabled, addreses for the Republic of Ireland will be returned in the English format.\n",
      "items": {
        "type": "object"
      }
    }
  }
}