Report a number range from the regulator's table

What the national regulator's own allocation table says about every block under one prefix: how many blocks are allocated, unassigned or reserved, who holds them and what share each holds, the network brand behind each holder and the share each brand holds, how much of the range is mobile or VoIP, and the place, time zones and line types the numbering plan names for it. For the North American tables it also counts the codes pooled into thousands-blocks — whose holder may not hold every number in them — and spans the dates the codes were assigned. The report counts codes; a lookup of a US number names the holder of the number's own thousands-block where NANPA lists it. Original allocation only — never who serves a number today, which no open table publishes.

It is the endpoint behind the public area-code pages, so screening a whole area code before a campaign, or checking a range a signup wave arrived from, is one call rather than a page scrape. country is an ISO 3166-1 alpha-2 code and prefix the digits of the range with no calling code: /v1/phone/block/us/415, /v1/phone/block/gb/20. A prefix written the way it is dialled inside the country, with the trunk prefix in front, is read without it, and the answer's prefix, the charge and the repeat marker are the stored form's: gb/020 as 20, gb/0161 as 161 and us/1212 as 212. Italy, Poland and Mexico dial no trunk prefix, so their digits are read as written. A longer prefix narrows the report to the blocks underneath it.

Guernsey, Jersey and the Isle of Man (gg, je, im) are answered from GB's table, as their lookups are, keeping only the blocks whose numbers are theirs. A country whose numbering plan Spaw does not carry, and a prefix no block starts with (for a Crown dependency, one that reaches outside its own numbers, such as /v1/phone/block/gg/20), both answer 404 PHONE_BLOCK_NOT_FOUND and cost nothing.

curl https://spaw.co/api/v1/phone/block/us/415 \
  -H "Authorization: Bearer sk_live_…"

const response = await fetch('https://spaw.co/api/v1/phone/block/us/415', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_live_…',
  },
});
const result = await response.json();

import requests

response = requests.get(
    'https://spaw.co/api/v1/phone/block/us/415',
    headers={'Authorization': 'Bearer sk_live_…'},
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/phone/block/us/415');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…'],
]);
$result = json_decode(curl_exec($ch), true);

from spaw import Client

client = Client('sk_live_…')
result = client.phone_block_report('us', '415')

import Spaw from 'spaw';

const spaw = new Spaw({ apiKey: 'sk_live_…' });
const result = await spaw.phoneBlockReport('us', '415');

use Spaw\Client;

$spaw = new Client('sk_live_…');
$result = $spaw->phoneBlockReport('us', '415');

{
    "success": true,
    "data": {
        "country": "US",
        "country_name": "United States",
        "calling_code": 1,
        "prefix": "415",
        "international_prefix": "+1 415",
        "place": "San Francisco, CA",
        "places": [],
        "timezones": [
            "America/Los_Angeles"
        ],
        "line_types": [
            "fixed_line_or_mobile"
        ],
        "example": "+1 415-200-0000",
        "blocks": {
            "total": 792,
            "allocated": 604,
            "unassigned": 171,
            "reserved": 17,
            "pooled": 431
        },
        "assigned": {
            "dated": 262,
            "first": "2001-01-12",
            "last": "2026-08-27"
        },
        "block_length": 6,
        "kinds": {
            "mobile": 41.2,
            "voip": 12.7,
            "unsettled": 46.1
        },
        "holders": [
            {
                "holder": "PACIFIC BELL",
                "brand": "AT&T",
                "kind": null,
                "blocks": 96,
                "share": 15.9
            },
            {
                "holder": "T-MOBILE USA, INC.",
                "brand": "T-Mobile",
                "kind": "mobile",
                "blocks": 71,
                "share": 11.8
            }
        ],
        "brands": [
            {
                "brand": "AT&T",
                "blocks": 158,
                "share": 26.2
            },
            {
                "brand": "T-Mobile",
                "blocks": 104,
                "share": 17.2
            }
        ],
        "feed": {
            "key": "nanpa",
            "dataset": "nanpa-co-codes",
            "version": "2026-09-04",
            "complete": true
        }
    },
    "meta": {
        "credits_used": 1,
        "credits_remaining": 9,
        "cache_hit": false,
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "PHONE_BLOCK_NOT_FOUND",
        "message": "No number block in US starts with 999.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}