binsearchlookup

Official Python client for the BinSearchLookup 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.

from binsearchlookup import BinSearchLookup

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

Usage

Single lookup

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.

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.

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.

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.

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.

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

API reference

Full endpoint and field reference: binsearchlookup.com/development/docs

Support

support@binsearchlookup.com

License

MIT