OpenAPI Spec View as Markdown

BIN lookup with Java

This page uses Java 11 or later and java.net.http.HttpClient. Create an API key in the quickstart. Read it from the environment variable BINLOOKUP_API_KEY.

Look up one BIN

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class BinLookup {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        String apiKey = System.getenv("BINLOOKUP_API_KEY");

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.binlookupapi.com/v1/bin"))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString("{\"number\":42467101}"))
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        int status = response.statusCode();
        if (status == 200) {
            System.out.println(response.body());
            System.out.println(response.headers().firstValue("X-Quota-Remaining").orElse(""));
        } else if (status == 401) {
            System.err.println("The API key is missing or not valid.");
        } else if (status == 403) {
            System.err.println(response.body());
        } else if (status == 404) {
            System.err.println("The BIN is not in the data.");
        } else if (status == 429) {
            System.err.println("The daily quota is used.");
        } else if (status == 400) {
            System.err.println(response.body());
        } else {
            System.err.println("The API returned HTTP " + status);
        }
    }
}

Parse data with your JSON library. The fields are in the API reference. On BLAPI-150KPM and above, the body also contains meta.longer_bin_available.

HTTP 403 is FORBIDDEN or FEATURE_NOT_AVAILABLE. Read the error field.

Look up many BINs

POST /v1/bins accepts 1 to 2,000 values. It requires BLAPI-500KPM, or a test-mode organisation. Each value uses one lookup.

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.binlookupapi.com/v1/bins"))
    .header("Authorization", "Bearer " + System.getenv("BINLOOKUP_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(
        "{\"numbers\":[400062,\"400597\",99999999]}"
    ))
    .build();

HttpResponse<String> response = client.send(
    request,
    HttpResponse.BodyHandlers.ofString()
);

if (response.statusCode() == 403 && response.body().contains("FEATURE_NOT_AVAILABLE")) {
    System.err.println("Batch lookup needs the BLAPI-500KPM plan.");
} else if (response.statusCode() == 200) {
    System.out.println(response.body());
}

The results array keeps your order. See Batch lookups. If the batch does not fit in the remaining quota, the status is 429 and no quota is used.