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, how much of the range is mobile or VoIP, and the place, time zones and line types the numbering plan names for 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 in national notation, with no calling code: /v1/phone/block/us/415, /v1/phone/block/gb/020. A longer prefix narrows the report to the blocks underneath it.

A country whose numbering plan Spaw does not carry — including a region whose numbers live in another's table, as the Crown dependencies do under GB — and a prefix no block starts with 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",
        "timezones": [
            "America/Los_Angeles"
        ],
        "line_types": [
            "fixed_line_or_mobile"
        ],
        "example": "+1 415-200-0000",
        "blocks": {
            "total": 792,
            "allocated": 604,
            "unassigned": 171,
            "reserved": 17
        },
        "block_length": 6,
        "kinds": {
            "mobile": 41.2,
            "voip": 12.7,
            "unsettled": 46.1
        },
        "holders": [
            {
                "holder": "PACIFIC BELL",
                "kind": null,
                "blocks": 96,
                "share": 15.9
            },
            {
                "holder": "T-MOBILE USA, INC.",
                "kind": "mobile",
                "blocks": 71,
                "share": 11.8
            }
        ],
        "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"
    }
}