> For the complete documentation index, see [llms.txt](https://docs.stopbot.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stopbot.net/v2/api-v2-documentation/blocker.md). # Blocker ### Endpoint ``` GET https://api.stopbot.net/services/blocker ``` ### Parameters | Parameter | Required | Description | | --------- | -------- | -------------------------- | | `apikey` | Yes | Your Stopbot API key | | `ip` | Yes | Visitor IP address | | `ua` | No | Visitor user agent | | `url` | No | Requested URL or page path | ### Example Request ```bash curl "https://api.stopbot.net/services/blocker?apikey={API_KEY}&ip=1.1.1.1&ua={USER_AGENT}&url=https%3A%2F%2Fexample.com" ``` ### Example Response ```json { "ip": "1.1.1.1", "hostname": "one.one.one.one", "asn": 13335, "userType": "hosting", "connectionType": "Corporate", "company": "Cloudflare, Inc.", "isp": "Cloudflare, Inc.", "city": "Sydney", "district": "", "region": "New South Wales", "postcode": "1001", "country": "Australia", "countryCode": "AU", "latitude": -33.8688, "longitude": 151.209, "timezone": "Australia/Sydney", "isAnycast": true, "device": "Desktop", "ua": "{USER_AGENT}", "isBot": 1, "blockAccess": 1, "threatURL": 0, "detectActivity": "BLOCK BY HOSTNAME DATABASE.", "status": "success", "executionTime": "5.17ms", "timeResponse": "2026-07-07 12:00:00" } ``` ### Invalid Input Example If the `ip` parameter is missing or is not a valid IPv4/IPv6 address, the Blocker endpoint returns `400 Bad Request`. Example request with invalid IP: ```bash curl "https://api.stopbot.net/services/blocker?apikey={API_KEY}&ip=not-an-ip&ua={USER_AGENT}&url=https%3A%2F%2Fexample.com" ``` Example response: ```json { "errorMessage": "IP format is invalid.", "status": "failed", "executionTime": "1.23ms", "timeResponse": "2026-07-07 12:00:00" } ``` ### Response Fields Successful Blocker responses may include the following fields: | Field | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ip` | Visitor IP address from the `ip` request parameter | | `hostname` | Hostname or PTR value resolved for the visitor IP. If no hostname is available, the IP itself may be returned | | `asn` | Autonomous System Number from IP geolocation data | | `userType` | Network user type from IP geolocation data. Current values are `business`, `cellular`, `hosting`, and `residential`. If unavailable, STOPBOT returns `unknown` | | `connectionType` | Network connection type from IP geolocation data. Current values are `Cable/DSL`, `Cellular`, `Corporate`, and `Dialup`. If unavailable, STOPBOT returns `unknown` | | `company` | Autonomous system organization or company name from IP geolocation data. If unavailable, STOPBOT returns `unknown` | | `isp` | Internet service provider name from IP geolocation data. If unavailable, STOPBOT returns `unknown` | | `city` | City name from IP geolocation data. If unavailable, STOPBOT may return `unknown` | | `district` | District or second subdivision from IP geolocation data when available | | `region` | Region or first subdivision from IP geolocation data. If unavailable, STOPBOT may return `unknown` | | `postcode` | Postal code from IP geolocation data when available | | `country` | Country name from IP geolocation data. If unavailable, STOPBOT returns `unknown` | | `countryCode` | Country ISO code from IP geolocation data. If unavailable, STOPBOT returns `NN` | | `latitude` | Latitude from IP geolocation data. If unavailable, the value may be `0` | | `longitude` | Longitude from IP geolocation data. If unavailable, the value may be `0` | | `timezone` | Timezone from IP geolocation data. If unavailable, STOPBOT returns `UTC` | | `isAnycast` | `true` when the IP geolocation data marks the IP as anycast; otherwise `false` | | `device` | Device classification derived from the `ua` request parameter | | `ua` | User agent value from the request. This field is only included when the `ua` parameter is provided | | `isBot` | Visitor classification signal: `0` visitor/non-bot, `1` detected bot/threat, `2` user list match | | `blockAccess` | `1` means the website should apply the block action; `0` means access can continue or be monitored | | `threatURL` | `1` when the URL is treated as a threat signal; otherwise `0` | | `detectActivity` | Detection reason returned by the Blocker decision flow | | `status` | API result status. Successful Blocker responses return `success` | | `executionTime` | Server-side execution time for the request | | `timeResponse` | Response timestamp in `YYYY-MM-DD HH:mm:ss` format | ### Error Response Fields Failed Blocker responses may include the following fields: | Field | Description | | --------------- | -------------------------------------------------- | | `errorMessage` | Human-readable error message | | `status` | Failed requests return `failed` | | `executionTime` | Server-side execution time for the request | | `timeResponse` | Response timestamp in `YYYY-MM-DD HH:mm:ss` format | ### Decision Fields | Field | Description | | ---------------- | ----------------------------------------------------------------------------- | | `isBot` | Bot classification. `0` visitor, `1` detected bot/threat, `2` user list match | | `blockAccess` | `1` means block action should be applied, `0` means allow/monitor | | `threatURL` | URL threat flag | | `detectActivity` | Human-readable detection reason | | `device` | Detected device type | Use `blockAccess` as the final allow/block decision field. The `isBot` field is a classification signal and should not be used as the final access decision. For the Blocker endpoint, most blocked threat or policy matches also return `isBot=1` or `isBot=2`, but the integration contract remains the same: apply your block action when `blockAccess` is `1`. ### Device Values The `device` field is derived from the `ua` request parameter. | Value | Meaning | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Mobile` | The user agent contains a known mobile keyword, such as Android, iPhone, iPad, Windows Phone, BlackBerry, Nokia, Kindle, PlayBook, `mobi`, Silk, Opera Mini, Opera Mobile, UCBrowser, Symbian, Blazer, or WebOS | | `Desktop` | The user agent does not match the mobile keyword list, or no user agent is provided | ### User Type The `userType` field is copied from the IP geolocation data field `traits.user_type`. The current STOPBOT IP geolocation database contains these `userType` values: | Value | Meaning | | ------------- | -------------------------------------- | | `business` | Business or organization network | | `cellular` | Mobile carrier network | | `hosting` | Hosting, cloud, or data center network | | `residential` | Residential ISP network | If the IP geolocation data does not provide a value, STOPBOT returns: ``` unknown ``` ### Connection Type The `connectionType` field is copied from the IP geolocation data field `traits.connection_type`. The current STOPBOT IP geolocation database contains these `connectionType` values: | Value | Meaning | | ----------- | ----------------------------------------------------- | | `Cable/DSL` | Fixed broadband connection | | `Cellular` | Mobile network connection | | `Corporate` | Corporate or organization network connection category | | `Dialup` | Dial-up connection | If the IP geolocation data does not provide a value, STOPBOT returns: ``` unknown ``` ### Common Detection Reasons | Value | Meaning | | ------------------------------------ | ------------------------------------------ | | `Visitor` | No block reason detected | | `BLOCK BY IP DATABASE.` | IP matched Stopbot IP database | | `BLOCK BY MALICIOUS ACTIVITY.` | IP matched malicious activity checks | | `BLOCK BY HOSTNAME DATABASE.` | Hostname matched Stopbot hostname database | | `BLOCK BY PROXY/VPN/TOR.` | Proxy, VPN, or Tor detection | | `BLOCK BY COUNTRY.` | Country is not allowed by configuration | | `BLOCK BY IP NON-ISP.` | Non-ISP network blocked by configuration | | `BLOCK BY SPIDER CRAWLER` | User agent bot/crawler detection | | `BLOCK BY THREAT URL` | URL threat or repeated failed traffic | | `BLOCK BY DEVICE DESKTOP` | Blocked by configured desktop device rule | | `BLOCK BY DEVICE MOBILE` | Blocked by configured mobile device rule | | `BLOCK BY BLACKLIST IP (USER)` | Matched user IP blacklist | | `ALLOW BY WHITELIST IP (USER)` | Matched user IP whitelist | | `BLOCK BY THREAT FEEDS` | Matched Stopbot threat feeds | | `BLOCK BY HOSTNAME (USER)` | Matched user hostname blacklist | | `ALLOW BY SETTING ( SEARCH ENGINE )` | Allowed search engine bot by setting |