# Single Lookup Tutorial
source: https://developer.mastercard.com/bin-lookup/documentation/tutorials-and-guides/single-lookup/index.md

## Overview {#overview}

This tutorial walks through how to perform a real-time single BIN lookup. This is useful when you want to check card details in advance of allowing a transaction to proceed in the checkout process. At the end of this tutorial you will have a Python script that will let you enter an 8 digit BIN via command line and receive the account range data for that BIN from the API.

### Prerequisites {#prerequisites}

For this tutorial you must ensure you have `Python` and `pip` installed on your system. If you don't already have Python installed, check out the [Getting Python guide](https://wiki.python.org/moin/BeginnersGuide).
Tip: If you have followed any other other tutorials you can skip step 1 \& 2 because they are the same for every tutorial. If you want to get straight to the code, all example files are available on [Github](https://github.com/Mastercard-Samples/bin-lookup-sample-code)

## 1. Create the File \& Download Dependencies {#1-create-the-file--download-dependencies}

First, we need to ensure to have the dependencies needed for our code. We install the `mastercard-oauth1-signer` and `requests` packages via the following command line:

```terminal
pip install mastercard-oauth1-signer requests
```

Next, create a file called `single-lookup-example.py` and add the following imports at the top of the file:

```python
import requests
from requests.auth import AuthBase
import oauth1.authenticationutils as authenticationutils
from oauth1.signer import OAuthSigner
import csv
```

## 2. Configuring Authentication {#2-configuring-authentication}

Next, create some variables to hold the base URL, which is the url for the API we will be calling, and for your consumer key. You can get your consumer key from your project in the projects dashboard.

```python
BASE_URL = 'Add Sandbox or Production BASE URL here'
CONSUMER_KEY = 'Add you project consumer key here' 
```

Following that, use the this code to create simple class that will sign all HTTP requests we send using the Python requests library:

```python
# MCSigner
# Helper class for signing request objects
class MCSigner(AuthBase):
    def __init__(self, consumer_key, signing_key):
        self.signer = OAuthSigner(consumer_key, signing_key)

    def __call__(self, request):
        self.signer.sign_request(request.url, request)
        return request
```

Finally, use the Mastercard OAuth library to create a signing key using the .p12 cert that you downloaded when you created your project, and the keystore password that you set:

```python
# Generate a signing key and use it, and consumer key, with the signer class
signing_key = authenticationutils.load_signing_key('./certs/sandbox.p12', 'keystorepassword')
signer = MCSigner(CONSUMER_KEY, signing_key)
```

## 3. Finding Details of a Single BIN {#3-finding-details-of-a-single-bin}

Now that we have our credentials configured and our requests handler setup for signing, we can begin calling the single lookup endpoint. This endpoint takes an 8 digit BIN as input and searches 90k+ account ranges to evaluate what range the BIN belongs in.

In our code lets ask for some input when we run the Python script, and place the captured input into the JSON format the endpoint expects:

```python
print("Enter a 8 digit BIN:")
bin = input()

lookup_bin = {
  "accountRange": bin
}
```

Next, lets use the requests library to send a POST with the lookup_bin JSON object to the endpoint:

```python
resp = requests.post(
        f'{BASE_URL}/bin-ranges/account-searches',
        auth=signer,
        json = lookup_bin
    )

print (resp.json())
```

To execute the Python script, use the following command:

```terminal
python single-lookup-example.py
```

Once the script executes you will be prompted to add in an 8 digit BIN, once you do the API will return any matches from the account ranges on record:

![How to search for BINs](https://static.developer.mastercard.com/content/bin-lookup/uploads/bin-search.png "How to search for BINs")

## Code {#code}

Here is the full Python source code:

```python
import requests
from requests.auth import AuthBase
import oauth1.authenticationutils as authenticationutils
from oauth1.signer import OAuthSigner
import csv

BASE_URL = 'Add Sandbox or Production BASE URL here'
CONSUMER_KEY = 'Add you project consumer key here' 

# MCSigner
# Helper class for signing request objects
class MCSigner(AuthBase):
    def __init__(self, consumer_key, signing_key):
        self.signer = OAuthSigner(consumer_key, signing_key)

    def __call__(self, request):
        self.signer.sign_request(request.url, request)
        return request

# Generate a signing key and use it, and consumer key, with the signer class
signing_key = authenticationutils.load_signing_key('./certs/sandbox.p12', 'keystorepassword')
signer = MCSigner(CONSUMER_KEY, signing_key)

print("Enter a 8 digit BIN:")
bin = input()

lookup_bin = {
  "accountRange": bin
}

resp = requests.post(
        f'{BASE_URL}/bin-ranges/account-searches',
        auth=signer,
        json = lookup_bin
    )

print (resp.json())
```