Country Calling Codes

Looks up a country by calling code (+44), ISO region (GB) or English country name and returns the calling code, every region that shares it, national number lengths, trunk and international dialing prefixes, example numbers and the leading digits of mobile and fixed-line numbers where the numbering plan defines them. Derived from open libphonenumber metadata and CLDR country names; it describes numbering-plan rules, not who is assigned a number.

POST https://YOUR_API_HOST/v1/country-code

Credits and caching

• Success billing. 1 credit per lookup (an unknown code, country or name is free). You are charged only when the lookup finds something; a not-found result is free.
• Results are cached per account for 7 days. Repeating the same lookup in that window is free and returns cache_hit: true.
• Invalid input, rate limits and errors are never charged.
• Read the billing rules for the full picture.

Request

Send a JSON body with Authorization: Bearer <key>. The body can be up to 64 KB.

Example request

curl -X POST https://YOUR_API_HOST/v1/country-code \
  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"+44"}'

1const response = await fetch("https://YOUR_API_HOST/v1/country-code", {
2  method: "POST",
3  headers: {
4    Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({
8    "query": "+44"
9  }),
10});
11​
12const result = await response.json();
13if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`);
14console.log(result.found, result.data, result.credits_charged);

1import os
2import requests
3​
4response = requests.post(
5    "https://YOUR_API_HOST/v1/country-code",
6    headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"},
7    json={
8        "query": "+44",
9    },
10    timeout=30,
11)
12result = response.json()
13if not response.ok:
14    raise RuntimeError(f"{result['error']['code']}: {result['error']['fix']}")
15print(result["found"], result["data"], result["credits_charged"])

Response

The status is 200 whether or not anything was found. Check found. Every response also carries the X-Request-Id, X-Credits-Charged, X-Credits-Remaining and X-RateLimit-* headers.

Envelope

The data object

Present when found is true, otherwise null.

_No fields._

Captured example (2026-10-18)

A real run of this lookup on 2026-10-18, using the request above, which is a public input. The envelope fields are left out.

1{
2  "product": "country-code",
3  "found": true,
4  "data": {
5    "kind": "calling_code",
6    "calling_code": "44",
7    "non_geographic": false,
8    "shared": true,
9    "main_region": "GB",
10    "regions": [
11      {
12        "region": "GB",
13        "name": "United Kingdom",
14        "region_leading_digits_pattern": null
15      },
16      {
17        "region": "GG",
18        "name": "Guernsey",
19        "region_leading_digits_pattern": null
20      },
21      {
22        "region": "IM",
23        "name": "Isle of Man",
24        "region_leading_digits_pattern": "74576|(?:16|7[56])24"
25      },
26      {
27        "region": "JE",
28        "name": "Jersey",
29        "region_leading_digits_pattern": null
30      }
31    ],
32    "numbering": null,
33    "notes": "Several regions share this calling code and are told apart by their number patterns, not by the code. main_region is the metadata default where shared formats are stored, not a political ranking."
34  },
35  "sources": [
36    "Google libphonenumber metadata (Apache-2.0) via libphonenumber-js 1.13.15 (MIT)",
37    "Country names from Unicode CLDR through Intl.DisplayNames (Unicode License 3.0)"
38  ]
39}

Errors

• 400 invalid_input: The request input is invalid.
• 401 unauthorized: The API key is missing, malformed, revoked or unknown.
• 402 insufficient_credits: The account does not have enough credits for this lookup. Error code: insufficient_credits. During a trial whose allowance is used up the code is trial_allowance_exhausted: nothing is charged and the customer starts the plan from the billing page.
• 405 method_not_allowed: This endpoint does not accept that HTTP method.
• 413 payload_too_large: The request body is too large.
• 429 rate_limited: Too many requests for this API key.
• 500 internal_error: An unexpected error occurred.
• 503 provider_unavailable: The data source for this product is unavailable right now.