usacallerlookup

usacallerlookup

Zero-dependency Node.js client for the free USA Caller Lookup API: reverse phone lookup, FTC robocall complaint data, and US area code information.

The API is free, needs no key, and covers every US NANP number reported in FTC Do Not Call complaints (200,000+ tracked numbers, refreshed every weekday). Aggregates are US public domain data (CC0).

Install

npm install usacallerlookup

Requires Node.js 18 or newer (uses the built-in fetch). No dependencies.

Usage

import { lookupNumber, areaCode, stats } from 'usacallerlookup';

// Reverse phone lookup: location, carrier, complaint history
const num = await lookupNumber('369-216-6437');
console.log(num.location);          // { city: 'Ukiah', state: 'CA', carrier: 'T-MOBILE USA, INC.' }
console.log(num.complaints.total);  // 1389
console.log(num.complaints.top_subjects[0].subject); // 'Reducing your debt...'

// Area code info: state, timezone, top cities, complaint totals
const ac = await areaCode(369);
console.log(ac.state, ac.timezone); // 'CA' 'P'

// Dataset-wide statistics
const s = await stats();
console.log(s.tracked_numbers, s.complaint_records);

CommonJS works too:

const { lookupNumber } = require('usacallerlookup');

Phone numbers are accepted in any common format: "2029671717", "202-967-1717", "(202) 967 1717", "+1 202 967 1717".

API

Function	Endpoint	Returns
lookupNumber(phone)	/number/{phone}	Location, carrier, toll-free flag, FTC complaint totals and subjects, community reports
areaCode(npa)	/area-code/{npa}	State, timezone, assigned prefixes, top cities, complaint totals
stats()	/stats	Tracked numbers, complaint records, robocall share, last refresh time

A number with no complaint history still returns a result (zero counts). An unknown area code rejects with a UCLError whose status is 404.

Every function takes an optional second argument { signal } for an AbortSignal.

Errors

All failures reject with UCLError, which carries status (HTTP status, or 0 for input and network errors) and code (invalid_input, rate_limited, network_error, or the API's error code).

Rate limit

60 requests per minute per IP. Exceeding it rejects with code: 'rate_limited' and status: 429. For bulk analysis, skip the API and use the full dataset instead (CSV, CC0, updated weekdays).

Data sources

• Where the data comes from: FTC Do Not Call complaints plus the NANPA numbering registry
• US robocall statistics
• Full dataset on GitHub and Kaggle
• API documentation

License

MIT for this client. The underlying aggregates are CC0 1.0 (US public domain source data).