usacallerlookup

Zero-dependency Python 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

pip install usacallerlookup

Requires Python 3.8 or newer. Uses only the standard library.

Usage

import usacallerlookup as ucl

# Reverse phone lookup: location, carrier, complaint history
num = ucl.lookup_number("369-216-6437")
print(num["location"])              # {'city': 'Ukiah', 'state': 'CA', 'carrier': 'T-MOBILE USA, INC.'}
print(num["complaints"]["total"])   # 1389
print(num["complaints"]["top_subjects"][0]["subject"])

# Area code info: state, timezone, top cities, complaint totals
ac = ucl.area_code(369)
print(ac["state"], ac["timezone"])  # CA P

# Dataset-wide statistics
s = ucl.stats()
print(s["tracked_numbers"], s["complaint_records"])

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

API

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

Every function takes an optional timeout keyword argument (seconds, default 10).

Errors

All failures raise 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 raises UCLError 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).