Name: BotSec API: IP Reputation, Bot Detection, BIN Lookup
Brand: botsec-labs
SKU: api-botsec-labs-botsec-api
Availability: InStock
Author: API Market

Rahmawati

# BotSec IP Intelligence and Security API

## Overview

The BotSec API gives you IP reputation, geolocation, device and bot detection, and card BIN lookups as JSON. Check whether an IP is a proxy, VPN or hosting address and should be blocked, combine an IP and User-Agent in one access check, detect bots and devices from a User-Agent, geolocate an IP, and look up the brand, type, bank and country of a card BIN.

It is built for fraud prevention, sign-up protection, analytics and payment teams who need quick signals about a visitor or a card. Each endpoint is a single GET request with an IP, User-Agent or BIN.

## Features

*   **6 endpoints**: block check, access check, device detection, fast and full geolocation, and BIN lookup.
*   **IP reputation**: blacklist status, a block or allow suggestion and the reason.
*   **Bot detection**: bot flag, device, browser and OS from a User-Agent.
*   **Geolocation**: country, region, city, ISP and more.
*   **BIN lookup**: card brand, type, category, bank and country.
*   **Rate limit**: 1 request per second on Free Trial, 10 on Pro, 30 on Ultra.

## Use Cases

*   **Fraud prevention**: flag proxy and hosting IPs at checkout.
*   **Sign-up protection**: block bots and abusive networks.
*   **Payments**: check a card's country and type from its BIN.
*   **Analytics**: enrich logs with location and device data.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/botsec-labs/botsec-api
```

### Authentication

Every request must include your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. IP threat check

Checks an IP's reputation and suggests whether to block it, with the reason.

**Method:** `GET`

**Endpoint:** `/block`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| ip | query | IPv4 or IPv6 address | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/botsec-labs/botsec-api/block?ip=185.220.101.1' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "status": "success",
  "message": "IP reputation checked.",
  "data": {
    "query": "185.220.101.1",
    "type": "IPv4",
    "is_private": false,
    "country": "Germany",
    "isp": "Stiftung Erneuerbare Freiheit",
    "org": "Artikel10 e.V",
    "is_blacklisted": true,
    "suggest": "block",
    "reason": "proxy"
  },
  "response": "95ms",
  "website": "https://botsec.dev",
  "contact": "https://t.me/AozoraKZ"
}
```

#### 2. Access check

Checks an IP and an optional User-Agent together and returns both results.

**Method:** `GET`

**Endpoint:** `/access`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| ip | query | IPv4 or IPv6 address | string | Yes | - | - |
| ua | query | User-Agent string | string | No | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/botsec-labs/botsec-api/access?ip=8.8.8.8&ua=Mozilla%2F5.0+%28Windows+NT+10.0%3B+Win64%3B+x64%29+AppleWebKit%2F537.36+Chrome%2F120.0+Safari%2F537.36' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "status": "success",
  "message": "Access check completed.",
  "data": {
    "ip": {
      "query": "8.8.8.8",
      "type": "IPv4",
      "is_private": false,
      "country": "United States",
      "isp": "Google LLC",
      "org": "Google Public DNS",
      "is_blacklisted": true,
      "suggest": "block",
      "reason": "proxy"
    },
    "ua": {
      "is_bot": false,
      "raw": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/120.0 Safari/537.36"
    }
  },
  "response": "258ms",
  "website": "https://botsec.dev",
  "contact": "https://t.me/AozoraKZ"
}
```

#### 3. Device and bot detection

Detects bots and the device, browser and operating system from a User-Agent.

**Method:** `GET`

**Endpoint:** `/device`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| ua | query | User-Agent string | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/botsec-labs/botsec-api/device?ua=Mozilla%2F5.0+%28iPhone%3B+CPU+iPhone+OS+17_0+like+Mac+OS+X%29+AppleWebKit%2F605.1.15+Mobile%2F15E148' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "status": "success",
  "message": "Device information retrieved successfully.",
  "data": {
    "is_bot": false,
    "device": {
      "name": "smartphone",
      "brand": "Apple",
      "model": "iPhone"
    },
    "client": {
      "type": "browser",
      "name": "Chrome",
      "short_name": "CH",
      "version": "157",
      "engine": "Blink",
      "engine_version": "157",
      "family": "Chrome"
    },
    "os": {
      "name": "Mac",
      "short_name": "MAC",
      "version": "",
      "platform": "",
      "family": "Mac"
    },
    "raw": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 Mobile/15E148"
  },
  "response": "804ms",
  "website": "https://botsec.dev",
  "contact": "https://t.me/AozoraKZ"
}
```

#### 4. Fast geolocation

Returns a quick country-level geolocation for an IP.

**Method:** `GET`

**Endpoint:** `/geolite`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| ip | query | IPv4 or IPv6 address | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/botsec-labs/botsec-api/geolite?ip=8.8.8.8' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "status": "success",
  "message": "Geolocation data retrieved successfully.",
  "data": {
    "ip": "8.8.8.8",
    "city": "",
    "country": "United States",
    "country_code": "US",
    "flags_icon": "https://pro.botsec.dev/icons/flags/us.png",
    "region": "",
    "region_code": "",
    "continent": "North America",
    "continent_code": "NA",
    "zip": "",
    "timezone": "America/Chicago",
    "latitude": 37.751,
    "longitude": -97.822,
    "accuracy_radius": 1000,
    "isp": "Google LLC",
    "as_number": "AS15169",
    "as_organization": "AS15169 - Google LLC"
  },
  "response": "6ms",
  "website": "https://botsec.dev",
  "contact": "https://t.me/AozoraKZ"
}
```

#### 5. Full geolocation

Returns the full geolocation of an IP, including city, region and ISP.

**Method:** `GET`

**Endpoint:** `/geo`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| ip | query | IPv4 or IPv6 address | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/botsec-labs/botsec-api/geo?ip=147.161.246.39' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "status": "success",
  "message": "Geolocation data retrieved successfully.",
  "data": {
    "ip": "147.161.246.39",
    "city": "Zurich",
    "country": "Switzerland",
    "country_code": "CH",
    "flags_icon": "https://pro.botsec.dev/icons/flags/ch.png",
    "region": "Zurich",
    "region_code": "ZH",
    "district": "",
    "continent": "Europe",
    "continent_code": "EU",
    "zip": "8000",
    "lat": 47.3643,
    "lon": 8.5437,
    "timezone": "Europe/Zurich",
    "offset": 3600,
    "currency": "CHF",
    "isp": "Zscaler Switzerland GmbH",
    "org": "Zscaler Zrh1",
    "as": "AS62044 Zscaler Switzerland GmbH",
    "asname": "ZSCALER-EMEA",
    "proxy": false,
    "hosting": true
  },
  "response": "81ms",
  "website": "https://botsec.dev",
  "contact": "https://t.me/AozoraKZ"
}
```

#### 6. BIN lookup

Returns the card brand, type, category, issuing bank and country for a BIN.

**Method:** `GET`

**Endpoint:** `/cards`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| bin | query | First 6 to 8 digits of the card number | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/botsec-labs/botsec-api/cards?bin=453201' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "status": "success",
  "message": "Card information retrieved successfully.",
  "data": {
    "bin": "453201",
    "card": {
      "brand": "VISA",
      "type": "CREDIT",
      "category": "PREMIER"
    },
    "bank": {
      "name": "BANCO CAMINOS, S.A.",
      "phone": "",
      "url": ""
    },
    "country": {
      "code": "ES",
      "code3": "ESP",
      "name": "Spain",
      "phone_code": "+34",
      "capital": "Madrid",
      "emoji": "🇪🇸"
    },
    "currency": {
      "symbol": "€",
      "code": "EUR",
      "name": "Euro"
    },
    "continent": {
      "name": "Europe",
      "code": "EU"
    }
  },
  "response": "0ms",
  "website": "https://botsec.dev",
  "contact": "https://t.me/AozoraKZ"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. Check the parameter table for the endpoint. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but your subscription does not allow this request, for example an endpoint outside your plan. |
| 404 | Not Found | The path does not exist, or the resource you asked for was not found. |
| 429 | Too Many Requests | You sent more requests per second than your plan allows (1 on Free Trial, 10 on Pro, 30 on Ultra). Slow down and retry, honouring the `Retry-After` header. |
| 500 | Internal Server Error | Something went wrong while processing the request. Retry after a short wait. |
| 503 | Service Unavailable | The service or its upstream data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

The request rate depends on your plan: 1 request per second on Free Trial, 10 on Pro and 30 on Ultra. Each plan also has a monthly call quota shown on the pricing page. Going over your plan's per-second limit returns `429 Too Many Requests`. Throttle your client to your plan's rate, back off and retry when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **Should I block every IP marked is_blacklisted?**

    Use `suggest` and `reason` as signals. Hosting and proxy IPs include corporate gateways and public DNS servers, so combine them with your own rules before blocking users.

*   **What is the difference between /geolite and /geo?**

    `/geolite` is a faster lookup with fewer fields. `/geo` returns the full location, including city, region and ISP.

*   **Does the BIN lookup need a full card number?**

    No. Send only the first 6 to 8 digits.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Check IP reputation and proxies, detect bots and devices, geolocate IPs and look up card BINs with simple GET requests.