Metadata-Version: 2.4
Name: binsearchlookup
Version: 0.1.1
Summary: Official Python client for the BinSearchLookup BIN lookup API
Author-email: BinSearchLookup <support@binsearchlookup.com>
License: MIT
Project-URL: Homepage, https://www.binsearchlookup.com/development/docs
Project-URL: Documentation, https://www.binsearchlookup.com/development/docs
Keywords: bin,iin,card,lookup,card-validation,payments
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Dynamic: license-file

# binsearchlookup

Official Python client for the [BinSearchLookup](https://www.binsearchlookup.com) API. Look up card BINs/IINs, search the dataset by issuer, brand, category, type or country, batch lookups, and Luhn-validate card numbers.

Requires Python 3.8+. Only dependency is `requests`.

## Install

```
pip install binsearchlookup
```

## Setup

Get your API key and user ID from your [dashboard](https://www.binsearchlookup.com/dashboard).

```python
from binsearchlookup import BinSearchLookup

bsl = BinSearchLookup(api_key="...", user_id="...")
```

## Usage

### Single lookup

```python
result = bsl.lookup("551029")
print(result["data"]["Issuer"], result["data"]["Brand"], result["data"]["Prepaid"])
print(result["data"]["similarBins"])  # up to 10 other BINs from the same issuer
```

### Batch lookup

Up to 50 BINs per call, still counts as a single request against your quota.

```python
batch = bsl.lookup_batch(["551029", "424242", "400005"])
```

### Search / filter

Filter the dataset by category, issuer, brand, type or country. At least one filter is required. `limit` is capped by your plan's requests-per-minute if you pass a higher number or omit it.

```python
results = bsl.search(issuer="LEWIS & CLARK BANK", limit=50)
prepaid_cards = bsl.search(category="PREPAID", country="US")
```

### Card validation

Luhn and length checks, enriched with BIN data. The full card number is never logged or stored server-side, only the first 8 digits go into your request history.

```python
check = bsl.validate("4111111111111111")
print(check["valid"], check["data"])
```

### Error handling

Every non-2xx response raises `BinSearchLookupError` with `code`, `status_code`, and the raw `response` body attached.

```python
from binsearchlookup import BinSearchLookup, BinSearchLookupError

try:
    bsl.lookup("123")  # too short
except BinSearchLookupError as err:
    print(err.status_code, err.code, err)
```

## Sandbox / test mode

Build and test against realistic fake data with a fixed key pair. No auth, no rate limit, no effect on your real account or quota.

```python
sandbox = BinSearchLookup(api_key="bsl_" + "a" * 64, user_id="00000000-0000-4000-8000-000000000000")
sandbox.lookup("551029")  # -> {"sandbox": True, "data": {...}}
```

## API reference

| Method | Endpoint | Notes |
|---|---|---|
| `lookup(bin)` | `GET /lookup` | Single BIN, 6-8 digits |
| `lookup_batch(bins)` | `POST /lookup/batch` | Up to 50 BINs, 1 request against quota |
| `search(...)` | `GET /lookup/search` | `category`, `issuer`, `brand`, `type`, `country`, `limit` |
| `validate(card_number)` | `POST /validate` | Luhn + length check, BIN-enriched |

Full endpoint and field reference: [binsearchlookup.com/development/docs](https://www.binsearchlookup.com/development/docs)

## Support

support@binsearchlookup.com

## License

MIT
