Other/API Reference - Ideal Postcodes

Availability

v1.0.0

Returns public information on key. Currently only returns whether the key is currently useable via the available property. Use this to discover if the key is useable before making further requests.

You may pass both API Keys (beginning ak_) and Sub-licensed Keys (beginning sl_).

Testing

To test your implementation of our API, you may use the following test keys.

iddqd Availability will return as true
idkfa Availability will return as false

Input

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "Your API Key. Typically beings `ak_`.\n\nAvailable from your dashboard\n"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false
}

Output

{
  "type": "object",
  "required": [
    "code",
    "message",
    "result"
  ],
  "properties": {
    "code": {
      "type": "integer",
      "format": "int32",
      "enum": [
        2000
      ]
    },
    "message": {
      "type": "string",
      "enum": [
        "Success"
      ]
    },
    "result": {
      "type": "object",
      "required": [
        "available",
        "context",
        "contexts"
      ],
      "properties": {
        "available": {
          "type": "boolean",
          "description": "Determines whether the key can be used by the requesting agent. \n\nReturns false if one of the following conditions are met:\n  - Key has no lookups remaining\n  - Daily limit has been reached on the key\n  - Daily individual limit has been reached\n  - Key is not being used via an authorised URL\n  - (Sublicensed key only) Key has a valid licensee attached\n  - (Sublicensed key only) Key is not being used via an authorised URL specified by licensee\n"
        },
        "context": {
          "description": "Returns current context if it is in the list of available contexts for this key.\n",
          "type": "object"
        },
        "contexts": {
          "type": "array",
          "description": "A list of available contexts for a key",
          "items": {
            "type": "object",
            "required": [
              "iso_3",
              "iso_2",
              "description",
              "emoji",
              "rgeo"
            ],
            "properties": {
              "description": {
                "type": "string",
                "description": "Country descriptor to show in Address Finder\n"
              },
              "emoji": {
                "type": "string",
                "description": "Emoji text icon"
              },
              "iso_2": {
                "type": "string",
                "description": "2 letter ISO code"
              },
              "iso_3": {
                "type": "string",
                "description": "3 letter ISO code"
              },
              "rgeo": {
                "type": "boolean",
                "description": "Indicates availability of reverse geolocation search\n"
              }
            }
          }
        }
      }
    }
  }
}