Methods¶
SmartBinDB provides both synchronous and asynchronous lookup methods. Choose the pattern that matches your application architecture.
Synchronous Methods¶
get_bin_info¶
- SmartBinDB.get_bin_info(bin)
Look up single BIN record by exact match (synchronous).
Hot path with single BIN_INDEX[key] access. Argument converted to string and whitespace stripped before lookup.
- Parameters:
bin – BIN to lookup, typically first 6-8 card digits. Whitespace trimmed automatically.
- Returns:
Standard response with single entry on success. Error envelope on miss with message echoing original query.
Example
db = SmartBinDB() result = db.get_bin_info("457173") if result["status"] == "SUCCESS": row = result["data"][0] print(row["brand"], row["issuer"], row["Country"]["Name"])
get_bins_by_bank¶
- SmartBinDB.get_bins_by_bank(bank, limit=None)
Return BIN records from banks matching substring (synchronous).
Case-insensitive substring match against issuer field across all country buckets. Scan short-circuits when limit is reached.
- Parameters:
bank – Case-insensitive issuer substring. “chase”, “Chase”, and “CHASE BANK” all match same records.
limit – Optional cap on returned records. Reduces CPU work.
- Returns:
Standard response. filtered_by set to “bank” on success.
Example
db = SmartBinDB() result = db.get_bins_by_bank("Chase", limit=5) for row in result["data"]: print(row["bin"], row["issuer"])
get_bins_by_country¶
- SmartBinDB.get_bins_by_country(country, limit=None)
Return BIN records for country code (synchronous).
Pseudo country “US” aggregates US, US1, US2 regional buckets and caps at 8000 records per call to keep payloads bounded.
- Parameters:
country – Alpha-2 country code (case-insensitive).
limit – Optional cap on returned records.
- Returns:
Standard response. filtered_by set to “country” on success.
Example
db = SmartBinDB() result = db.get_bins_by_country("BD", limit=20) print(result["count"])
Asynchronous Methods¶
aget_bin_info¶
- async SmartBinDB.aget_bin_info(bin)
Look up single BIN record by exact match (asynchronous).
True async implementation using asyncio for non-blocking operation. Defers CPU-bound work to thread pool to avoid blocking event loop.
- Parameters:
bin – BIN to lookup, typically first 6-8 card digits. Whitespace trimmed automatically.
- Returns:
Standard response with single entry on success. Error envelope on miss with message echoing original query.
Example
db = SmartBinDB() result = await db.aget_bin_info("457173") if result["status"] == "SUCCESS": row = result["data"][0] print(row["brand"], row["issuer"], row["Country"]["Name"])
aget_bins_by_bank¶
- async SmartBinDB.aget_bins_by_bank(bank, limit=None)
Return BIN records from banks matching substring (asynchronous).
True async implementation using asyncio for non-blocking operation. Defers CPU-bound work to thread pool to avoid blocking event loop.
- Parameters:
bank – Case-insensitive issuer substring. “chase”, “Chase”, and “CHASE BANK” all match same records.
limit – Optional cap on returned records. Reduces CPU work.
- Returns:
Standard response. filtered_by set to “bank” on success.
Example
db = SmartBinDB() result = await db.aget_bins_by_bank("Chase", limit=5) for row in result["data"]: print(row["bin"], row["issuer"])
aget_bins_by_country¶
- async SmartBinDB.aget_bins_by_country(country, limit=None)
Return BIN records for country code (asynchronous).
True async implementation using asyncio for non-blocking operation. Defers CPU-bound work to thread pool to avoid blocking event loop.
Pseudo country “US” aggregates US, US1, US2 regional buckets and caps at 8000 records per call to keep payloads bounded.
- Parameters:
country – Alpha-2 country code (case-insensitive).
limit – Optional cap on returned records.
- Returns:
Standard response. filtered_by set to “country” on success.
Example
db = SmartBinDB() result = await db.aget_bins_by_country("BD", limit=20) print(result["count"])
Helper Methods¶
get_country_info¶
- SmartBinDB.get_country_info(country_code)
Return ISO country metadata for alpha-2 country code.
Wrapped with LRU cache (256 max). Repeated calls for same country are essentially free after first lookup.
- Parameters:
country_code – 2-letter country code. Special values “US1” and “US2” are normalized to “US”.
- Returns:
Dictionary with A2, A3, N3, Name, and Cont keys. Unknown codes return empty strings for all fields except A2.
Example
db = SmartBinDB() print(db.get_country_info("BD")) print(db.get_country_info("ZZ"))
format_entry¶
- SmartBinDB.format_entry(entry, country_code)
Normalize raw BIN record into public response schema.
Raw entries from pickle are partially typed with possible missing fields. This produces the stable public shape documented in response schema.
- Parameters:
entry – Raw BIN entry from database. May have bin, brand, category, type, issuer, phone, website, country_code_alpha3 keys.
country_code – Country code for entry. Passed to get_country_info.
- Returns:
Normalized BIN record with complete response schema.
Example
db = SmartBinDB() raw = {"bin": "457173", "brand": "VISA", "type": "credit"} print(db.format_entry(raw, "BD"))
load_data¶
- SmartBinDB.load_data()
Load bundled binary database into memory.
If the database file is missing or unreadable, the error is logged and in-memory structures remain empty. Public calls will attempt reload before returning an error envelope.
Example
db = SmartBinDB() db.COUNTRY_DATA.clear() db.load_data() assert db.COUNTRY_DATA