binDB 0.1.8
A Python library for retrieving BIN (Bank Identification Number) information.
Requires Python: >=3.6

# binDB

**Credit**: This library is a synchronous adaptation of the original `smartbindb` library which is asynchronous found at [https://pypi.org/project/smartbindb/](https://pypi.org/project/smartbindb/).

A Python library for retrieving BIN (Bank Identification Number) information.

## Installation

You can install `binDB` using pip:

```bash
pip install binDB
```

## Usage

```python
from binDB import BinDB

db = BinDB()

# Get BIN information
bin_info = db.get_bin_info("45717360")
print(bin_info)

# Get BINs by bank name
bank_bins = db.get_bins_by_bank("JPMorgan Chase", limit=5)
print(bank_bins)

# Get BINs by country code
country_bins = db.get_bins_by_country("US", limit=5)
print(country_bins)
```

## Available Methods (Endpoints)

The `BinDB` class provides the following methods for interacting with BIN data:

### `get_bin_info(bin: str) -> dict`
Retrieves detailed information for a specific BIN.
- `bin`: The 6-digit BIN to look up.

### `get_bins_by_bank(bank: str, limit: Optional[int] = None, fuzzy_match_threshold: int = 80) -> dict`
Retrieves BINs associated with a specific bank name. Supports fuzzy matching.
- `bank`: The name of the bank to search for.
- `limit`: (Optional) Maximum number of results to return.
- `fuzzy_match_threshold`: (Optional) Score threshold for fuzzy matching (default: 80).

### `get_bins_by_country(country: str, limit: Optional[int] = None, randomize: bool = False) -> dict`
Retrieves BINs for a specific country.
- `country`: The two-letter ISO country code (e.g., "US", "GB").
- `limit`: (Optional) Maximum number of results to return.
- `randomize`: (Optional) If `True`, returns a random sample of BINs (default: `False`).

### `get_bins(country_code: Optional[str] = None, limit: int = 10, randomize: bool = False) -> dict`
Retrieves a list of BINs, optionally filtered by country.
- `country_code`: (Optional) The two-letter ISO country code. If `None`, retrieves BINs from all countries.
- `limit`: Maximum number of results to return (default: 10).
- `randomize`: If `True`, returns a random sample of BINs (default: `False`).

### `get_all_bank_names(country_code: Optional[str] = None, count_bins: bool = False) -> List[Dict]`
Retrieves a list of all unique bank names in the database, optionally filtered by country and with BIN counts.
- `country_code`: (Optional) The two-letter ISO country code.
- `count_bins`: If `True`, includes the count of BINs for each bank (default: `False`).

### `get_total_bins_count() -> int`
Returns the total number of unique BINs loaded in the database.

### `get_country_bin_counts() -> dict`
Returns a dictionary with country codes as keys and the number of BINs for each country as values, sorted by count in descending order.

## Data

The library uses JSON files located in the `data/` directory for BIN information.

## Contributing

Feel free to contribute to this project by opening issues or pull requests on GitHub.

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.
# binDB

A Python library for retrieving BIN (Bank Identification Number) information.

## Installation

You can install `binDB` using pip:

```bash
pip install binDB
```

## Usage

```python
from binDB.smartdb import SmartBinDB

db = SmartBinDB()

# Get BIN information
bin_info = db.get_bin_info("45717360")
print(bin_info)

# Get BINs by bank name
bank_bins = db.get_bins_by_bank("JPMorgan Chase", limit=5)
print(bank_bins)

# Get BINs by country code
country_bins = db.get_bins_by_country("US", limit=5)
print(country_bins)
```

## Available Methods (Endpoints)

The `SmartBinDB` class provides the following methods for interacting with BIN data:

### `get_bin_info(bin: str) -> dict`
Retrieves detailed information for a specific BIN.
- `bin`: The 6-digit BIN to look up.

### `get_bins_by_bank(bank: str, limit: Optional[int] = None, fuzzy_match_threshold: int = 80) -> dict`
Retrieves BINs associated with a specific bank name. Supports fuzzy matching.
- `bank`: The name of the bank to search for.
- `limit`: (Optional) Maximum number of results to return.
- `fuzzy_match_threshold`: (Optional) Score threshold for fuzzy matching (default: 80).

### `get_bins_by_country(country: str, limit: Optional[int] = None, randomize: bool = False) -> dict`
Retrieves BINs for a specific country.
- `country`: The two-letter ISO country code (e.g., "US", "GB").
- `limit`: (Optional) Maximum number of results to return.
- `randomize`: (Optional) If `True`, returns a random sample of BINs (default: `False`).

### `get_bins(country_code: Optional[str] = None, limit: int = 10, randomize: bool = False) -> dict`
Retrieves a list of BINs, optionally filtered by country.
- `country_code`: (Optional) The two-letter ISO country code. If `None`, retrieves BINs from all countries.
- `limit`: Maximum number of results to return (default: 10).
- `randomize`: If `True`, returns a random sample of BINs (default: `False`).

### `get_all_bank_names(country_code: Optional[str] = None, count_bins: bool = False) -> List[Dict]`
Retrieves a list of all unique bank names in the database, optionally filtered by country and with BIN counts.
- `country_code`: (Optional) The two-letter ISO country code.
- `count_bins`: If `True`, includes the count of BINs for each bank (default: `False`).

### `get_total_bins_count() -> int`
Returns the total number of unique BINs loaded in the database.

### `get_country_bin_counts() -> dict`
Returns a dictionary with country codes as keys and the number of BINs for each country as values, sorted by count in descending order.

## Data

The library uses JSON files located in the `data/` directory for BIN information.

## Contributing

Feel free to contribute to this project by opening issues or pull requests on GitHub.

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.