Key Availability

GET/v1/keys/{key}

Returns public information on an API Key: whether it can be used right now (available), the search contexts the key is licensed for (contexts) and the context that best matches the caller's IP address (context).

The endpoint accepts API Keys (beginning ak_) and sub-licensed keys (beginning sl_), and needs no user_token.

A key that exists but cannot be used, because it has no lookups left or has breached a limit, returns 200 with "available": false. An unknown or malformed key returns an error.

Supply a valid user_token and the endpoint returns the key's private details instead, as GET /keys/{key}/details does. A user_token that does not own the key is rejected.

Path parameters

key string

API Key

The API Key to retrieve. Begins ak_.

Example ak_test

Response

result is a small, fixed object — shown here in full. Each address record in contexts describes a country the key may search within.

• result ApiKey

  • contexts object[]

    A list of available contexts for a key

    • iso_3 string

      3 letter ISO code

      Example

      USA

    • iso_2 string

      2 letter ISO code

      Example

      US

    • description string

      Country descriptor to show in Address Finder

      Example

      United States

    • emoji string

      Emoji text icon

      Example

      🇺🇸

    • rgeo boolean

      Indicates availability of reverse geolocation search

      Example

      true

  • context one of

    Returns current context if it is in the list of available contexts for this key.

    • string

      Limits search results within a geographical boundary or country.

    • string

      Empty string if no context is provided or key check has failed

      Values

      • ""

  • available boolean

    Determines whether the key can be used by the requesting agent.

    Returns false if one of the following conditions are met:

    • Key has no lookups remaining
    • Daily limit has been reached on the key
    • Daily individual limit has been reached
    • Key is not being used via an authorised URL
    • (Sublicensed key only) Key has a valid licensee attached
    • (Sublicensed key only) Key is not being used via an authorised URL specified by licensee

    Example

    true

The result sits inside the standard { result, code, message } envelope — see the API reference for the wrapper format.

Request

URL

https://api.ideal-postcodes.co.uk/v1/keys/ak_test

curl

curl 'https://api.ideal-postcodes.co.uk/v1/keys/ak_test'

JavaScript

const response = await fetch('https://api.ideal-postcodes.co.uk/v1/keys/ak_test');

const { result } = await response.json();

Python

import requests

response = requests.get("https://api.ideal-postcodes.co.uk/v1/keys/ak_test")
result = response.json()["result"]

Ruby

require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/keys/ak_test")
result = JSON.parse(Net::HTTP.get(uri))["result"]

PHP

<?php
$response = file_get_contents("https://api.ideal-postcodes.co.uk/v1/keys/ak_test");
$result = json_decode($response, true)["result"];

Response

200 OK

{
  "result": {
    "contexts": [
      {
        "iso_3": "USA",
        "iso_2": "US",
        "description": "United States",
        "emoji": "🇺🇸",
        "rgeo": true
      }
    ],
    "context": "",
    "available": true
  },
  "message": "Success",
  "code": 2000
}

404 Not Found

response.json

{
  "code": 4040,
  "message": "Invalid Key"
}