Key Details

GET/v1/keys/{key}/details

Returns private data on a key: remaining lookups, licensed datasets, usage limits, notification settings and the search contexts the key can serve.

Path parameters

key string

API Key

The API Key to retrieve. Begins ak_.

Example ak_test

Query parameters

user_token string optional

Private User Token

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically begins uk_...

Example uk_B59ScW1p1HHouf1VqclEPZUx

Response

result is a single object describing the key — shown here in full.

• result ApiKeyDetails

  • name string

    A name for the key

    Example

    My API Key

  • 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

  • lookups_remaining integer

    Format

    int32

    Example

    19889

  • daily_limit ApiKeyDailyLimit

    • limit integer

      number or null. The daily lookup limit currently set on your key. null means the limit is currently disabled.

      Format

      int32

      Example

      1000

    • consumed integer

      Number of lookups performed today which count towards your daily limit.

      Format

      int32

      Example

      288

  • monthly_limit ApiKeyMonthlyLimit

    • limit integer

      number or null. The monthly lookup limit currently set on your key. null means the limit is currently disabled.

      Format

      int32

      Example

      10000

    • consumed integer

      Number of lookups performed this month which count towards your monthly limit.

      Format

      int32

      Example

      2500

  • individual_limit ApiKeyIndividualLimit

    • limit integer

      number or null Limit set on the number of lookups that can be performed from a single IP address. null means the limit is currently disabled.

      Format

      int32

      Example

      30

  • allowed_urls string[]

    A list of allowed URLs. An empty list means that allowed URLs are disabled.

  • redact_days integer

    Number of days to preserve personal data stored in your key usage history. Set to 0 to prevent personal data storage

    Default

    28

  • notifications ApiKeyNotifications

    • emails string[]

      A list of email addresses designated by you to receive notifications about this key.

    • enabled boolean

      Indicates whether email notifications are enabled.

    • balance_threshold integer

      Balance threshold that triggers a reminder email. null means disabled.

      Format

      int32

      Example

      500

    • no_balance boolean

      Send notice when balance hits zero.

    • limit_reached boolean

      Send notice when rate limit is reached.

  • datasets ApiKeyDatasets

    Indicates which datasets are available and added by default to the address responses

    • paf boolean

      UK Main Address File (Postcode Address File)

      Example

      true

    • pafa boolean

      UK Property Alias dataset

      Example

      false

    • pafw boolean

      UK Welsh Language Dataset

      Example

      false

    • mr boolean

      UK Multiple Residence Dataset

      Example

      true

    • nyb boolean

      UK Not Yet Built Dataset

      Example

      false

    • ab boolean

      UK AddressBase dataset

      Example

      false

    • abp boolean optional

      UK AddressBase Premium dataset

      Example

      false

    • nip boolean

      Northern Ireland Pointer Dataset

      Example

      false

    • usps boolean

      US Address Dataset

      Example

      true

    • ecad boolean

      Republic of Ireland: Eircode Address Database

      Example

      false

    • ecaf boolean

      Republic of Ireland: Eircode Address File

      Example

      false

    • gnaf boolean

      Australia: Geocoded National Address File

      Example

      true

    • hereap boolean

      Asia Pacific Address File

      Example

      true

    • herehk boolean

      Hong Kong Address File

      Example

      true

    • herei boolean

      India Address File

      Example

      true

    • herem boolean

      Macau Address File

      Example

      true

    • heremea boolean

      Middle East and Africa Address File

      Example

      true

    • heremeas boolean

      Middle East and Africa Standalone Intermediate Maps Address File

      Example

      true

    • herena boolean

      North America Address File

      Example

      true

    • hereo boolean

      Oceania Address File

      Example

      true

    • heresa boolean

      South America Address File

      Example

      true

    • heret boolean

      Taiwan Address File

      Example

      true

    • hereee boolean

      Eastern Europe Address File

      Example

      true

    • herewe boolean

      Western Europe Address File

      Example

      true

    • phone boolean

      Phone validation is enabled

      Example

      true

    • email boolean

      Email validation is enabled

      Example

      true

    • kadaster boolean

      Netherlands: Kadaster BAG 2.0 Address File

    • kartverket boolean

      Norway: Kartverket Address File

      Example

      true

    • mois boolean

      South Korea: MOIS Address File

      Example

      true

    • sdfi boolean

      Denmark: Danmarks Adresseregister (DAR)

      Example

      true

    • cannar boolean

      Canada: Statistics Canada National Address Register

      Example

      true

    • fodbosa boolean

      Belgium: FOD BOSA Address File

      Example

      true

    • upujp boolean

      Japan: UPU Address File

      Example

      true

    • bev boolean

      Austria: BEV Address File

      Example

      true

    • ban boolean

      France: BAN (Base Adresse Nationale)

      Example

      true

    • swt boolean

      Switzerland and Liechtenstein: Swisstopo Address File

      Example

      true

    • gbrcleanse boolean

      UK GBR Cleanse

      Example

      true

    • uspscleanse boolean

      US CASS Cleanse

      Example

      true

  • automated_topups ApiKeyAutomatedTopup

    Automated topup status

    • enabled boolean

      Indicates whether automated top-ups are enabled

      Example

      true

  • current_purchases object[]

    Current balance purchases attached to key.

    • expires string

      string or null The date when this purchase will expire in simplified extended ISO format (ISO 8601). This is typically 365 days from the time of first use. This field will be null if the purchase has not yet been used.

      Example

      2022-01-06T11:41:27.092Z

    • purchased integer

      Number of procured lookups from this purchase.

      Format

      int32

      Example

      20000

    • consumed integer

      Number of consumed lookups off this purchase.

      Format

      int32

      Example

      121

  • ip_forwarding boolean

    Accept IP addresses forwarded in the AZ-Source-IP header

    Default

    false

  • premier_support boolean

    Whether the key is enrolled in the premier support programme and monitored closely by our devops team. Read-only; managed by our team.

    Default

    false

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

Request

URL

https://api.addresszen.com/v1/keys/ak_test/details?user_token=uk_secret

curl

curl -G 'https://api.addresszen.com/v1/keys/ak_test/details' \
  -d 'user_token=uk_secret'

JavaScript

const response = await fetch(
  'https://api.addresszen.com/v1/keys/ak_test/details?' +
  new URLSearchParams({
    user_token: 'uk_secret',
  })
);

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

Python

import requests

response = requests.get(
    "https://api.addresszen.com/v1/keys/ak_test/details",
    params={
        "user_token": "uk_secret",
    },
)
result = response.json()["result"]

Ruby

require "net/http"
require "json"

uri = URI("https://api.addresszen.com/v1/keys/ak_test/details")
uri.query = URI.encode_www_form(user_token: "uk_secret")
result = JSON.parse(Net::HTTP.get(uri))["result"]

PHP

<?php
$response = file_get_contents(
  "https://api.addresszen.com/v1/keys/ak_test/details?" .
  http_build_query([
    "user_token" => "uk_secret",
  ])
);
$result = json_decode($response, true)["result"];

Response

200 OK

{
  "result": {
    "name": "My API Key",
    "contexts": [
      {
        "iso_3": "USA",
        "iso_2": "US",
        "description": "United States",
        "emoji": "🇺🇸",
        "rgeo": true
      }
    ],
    "lookups_remaining": 19889,
    "daily_limit": {
      "limit": 1000,
      "consumed": 288
    },
    "monthly_limit": {
      "limit": 10000,
      "consumed": 2500
    },
    "individual_limit": {
      "limit": 30
    },
    "allowed_urls": [
      ""
    ],
    "redact_days": 28,
    "notifications": {
      "emails": [
        "person@example.com"
      ],
      "enabled": true,
      "balance_threshold": 500,
      "no_balance": true,
      "limit_reached": true
    },
    "datasets": {
      "paf": true,
      "pafa": false,
      "pafw": false,
      "mr": true,
      "nyb": false,
      "ab": false,
      "abp": false,
      "nip": false,
      "usps": true,
      "ecad": false,
      "ecaf": false,
      "gnaf": true,
      "hereap": true,
      "herehk": true,
      "herei": true,
      "herem": true,
      "heremea": true,
      "heremeas": true,
      "herena": true,
      "hereo": true,
      "heresa": true,
      "heret": true,
      "hereee": true,
      "herewe": true,
      "phone": true,
      "email": true,
      "kadaster": true,
      "kartverket": true,
      "mois": true,
      "sdfi": true,
      "cannar": true,
      "fodbosa": true,
      "upujp": true,
      "bev": true,
      "ban": true,
      "swt": true,
      "gbrcleanse": true,
      "uspscleanse": true
    },
    "automated_topups": {
      "enabled": true
    },
    "current_purchases": [
      {
        "expires": "2022-01-06T11:41:27.092Z",
        "purchased": 20000,
        "consumed": 121
      }
    ],
    "ip_forwarding": false,
    "premier_support": false
  },
  "code": 2000,
  "message": "Success"
}

401 Unauthorised

response.json

{
  "code": 4010,
  "message": "Invalid token"
}

404 Not Found

response.json

{
  "code": 4040,
  "message": "Not found"
}