The JSON endpoint

The checker on the home page, as JSON: what the national numbering plan says about one number. Free, without a key, 60 requests a minute and 2,000 a day per address. It reads the published plans only, so it says whether a number is valid, where and of which type, how to write it, and which carrier its block was allocated to. It cannot say whether the number is in service or who serves it today.

Calling it

Put the number in the path from a terminal: curl, HTTPie and Wget get pretty-printed JSON (any client sendingAccept: application/json does too); a browser on the same address lands on the checker. From code, call/v1/number with q, the number as typed, and region, the two-letter country code, when the number is written without its country code.

curl

curl https://phonelookup.dev/+447400123456
curl "https://phonelookup.dev/v1/number?q=07400%20123456&region=GB"

HTTPie

http https://phonelookup.dev/+447400123456

JavaScript

const res = await fetch('https://phonelookup.dev/v1/number?' + new URLSearchParams({ q: '07400 123456', region: 'GB' }))
const n = await res.json()
console.log(n.valid, n.type, n.e164) // true 'Mobile' '+447400123456'

Python

import json, urllib.parse, urllib.request

query = urllib.parse.urlencode({"q": "07400 123456", "region": "GB"})
with urllib.request.urlopen(f"https://phonelookup.dev/v1/number?{query}") as res:
    n = json.load(res)
print(n["valid"], n["type"], n["e164"])  # True Mobile +447400123456

The answer

{
  "input": "+447400123456",
  "valid": true,
  "possible": true,
  "reason": null,
  "region": "GB",
  "callingCode": 44,
  "e164": "+447400123456",
  "type": "Mobile",
  "parts": {
    "countryCode": "+44",
    "destinationCode": "7400",
    "destinationKind": "network code",
    "subscriber": "123456"
  },
  "formats": {
    "e164": "+447400123456",
    "international": "+44 7400 123456",
    "national": "07400 123456",
    "rfc3966": "tel:+44-7400-123456"
  },
  "carrier": "Three",
  "nanp": null,
  "references": [
    {
      "authority": "Ofcom",
      "title": "National Telephone Numbering Plan",
      "url": "https://www.ofcom.org.uk/phones-and-broadband/phone-numbers/numbering"
    },
    {
      "authority": "ITU",
      "title": "National numbering plan: United Kingdom",
      "url": "https://www.itu.int/oth/T02020000DD/en"
    }
  ]
}

Field	Type	What it says
input	string	The number as received, trimmed (at most 40 characters).
valid	boolean	True when the number falls in a range the numbering plan allocates.
possible	boolean	True when its length is one the plan allows, valid or not.
reason	string \| null	Why it is not valid: not_a_number (unreadable) or invalid_for_region. Null when valid.
region	string \| null	ISO 3166-1 alpha-2 code of the territory whose plan the number belongs to.
callingCode	integer \| null	The country calling code (ITU-T E.164), without the +.
e164	string \| null	The number in E.164: +, country code, national significant number.
type	string \| null	The line type of its range: Mobile, Fixed line, Fixed line or mobile, Toll-free, VoIP, Premium-rate, Shared cost, Personal number, Pager, UAN, Voicemail, Unknown. Null when not valid.
parts	object \| null	countryCode, destinationCode (the area or network code, where the plan has one), destinationKind ("area code" or "network code"), subscriber.
formats	object \| null	e164, international, national and rfc3966 (the tel: URI).
carrier	string \| null	The carrier the number's block was originally allocated to, where on record. Not necessarily the carrier serving it today (number portability).
nanp	object \| null	For +1 numbers of the United States and Canada: npa (area code), nxx (central office code), state or province, and the lineType the exchange was allocated as (mobile, fixed_line, voip, unknown).
references	array	The authorities for the plan: the regulator where on record and the plan as notified to the ITU, each with authority, title and url.

Errors and limits

A number the plan does not allocate: Still 200: valid is false and reason says why (not_a_number when it cannot be read as one, invalid_for_region when it can but falls outside every range).
400 invalid_request: q is missing.
429 rate_limited: More than 60 requests in a minute or 2,000 in a day from one address;Retry-After says how many seconds to wait. For lists, read the plans as JSON below and validate locally: the guides give a tested file per language that does exactly that.

The plans as files

/openapi.json: this endpoint described in OpenAPI 3.1, for code generators and agents.
/country.json: the 235 published plans, each with its page and its data.
/country/gb.json and one per country: the data its page is built from (formats, lengths, the pattern per line type, carrier blocks, the authorities cited).
/llms.txt and /llms-full.txt: the site and every plan in plain text, for language models.