Home »
SmartBinDB

SmartBinDB¶

class smartbindb.SmartBinDB¶

Bases: object

High-performance offline BIN lookup with true sync/async support.

Loads bundled BIN database into memory with O(1) indices. Provides independent synchronous and asynchronous implementations for flexible integration with any application architecture.

COUNTRY_JSON_DIR¶

Directory containing bundled binary database.

Type:: str

BINARY_DB¶

Absolute path to binary database file.

Type:: str

BIN_INDEX¶

O(1) lookup mapping from BIN string to entry tuples.

Type:: dict

COUNTRY_DATA¶

Mapping from country code to BIN entry lists.

Type:: dict

START_TIME¶

Process start time in epoch seconds.

Type:: float

Example

from smartbindb import SmartBinDB

db = SmartBinDB()

result = db.get_bin_info("457173")
print(result)

result_async = await db.aget_bin_info("457173")
print(result_async)

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

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(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"))

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(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(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"])

async 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"])

async 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"])

async 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"])