Metadata-Version: 2.4
Name: usacallerlookup
Version: 1.0.0
Summary: Zero-dependency client for the free USA Caller Lookup API: reverse phone lookup, FTC robocall complaint data, and US area code information.
Author-email: Public Data Depot <contact@usacallerlookup.com>
License: MIT
Project-URL: Homepage, https://www.usacallerlookup.com/api/
Project-URL: Documentation, https://www.usacallerlookup.com/api/
Project-URL: Repository, https://github.com/usacallerlookup/api-clients
Project-URL: Issues, https://github.com/usacallerlookup/api-clients/issues
Project-URL: Dataset, https://github.com/usacallerlookup/ftc-robocall-dataset
Keywords: reverse phone lookup,phone lookup,robocall,spam calls,ftc,do not call,caller id,phone number,area code,nanpa
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# usacallerlookup

Zero-dependency Python client for the free [USA Caller Lookup API](https://www.usacallerlookup.com/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

```bash
pip install usacallerlookup
```

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

## Usage

```python
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

| Function | Endpoint | Returns |
| --- | --- | --- |
| `lookup_number(phone)` | `/number/{phone}` | Location, carrier, toll-free flag, FTC complaint totals and subjects, community reports |
| `area_code(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 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](https://github.com/usacallerlookup/ftc-robocall-dataset) instead (CSV, CC0, updated weekdays).

## Data sources

- [Where the data comes from](https://www.usacallerlookup.com/data-sources/): FTC Do Not Call complaints plus the NANPA numbering registry
- [US robocall statistics](https://www.usacallerlookup.com/robocall-statistics/)
- [Full dataset on GitHub](https://github.com/usacallerlookup/ftc-robocall-dataset) and [Kaggle](https://www.kaggle.com/datasets/publicdatadepot/us-robocall-complaints-by-phone-number)
- [API documentation](https://www.usacallerlookup.com/api/)

## License

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