Code Examples

Ready-to-use snippets for score, classification, network, and evidence.signals.

cURL

Basic Lookup

curl -s https://api.ipbot.com/v1/ip/8.8.8.8 | jq
curl -s https://api.ipbot.com/v1/ip/current | jq

With API Key

curl -s -H "X-API-Key: ipb_free_REPLACE_ME" \
  https://api.ipbot.com/v1/ip/8.8.8.8 | jq

Extract Fields

# Ask the API to return only selected top-level fields
curl -s "https://api.ipbot.com/v1/ip/8.8.8.8?fields=ip,location,score" | jq

# Country and network category
curl -s https://api.ipbot.com/v1/ip/8.8.8.8 \
  | jq '{country: .location.country_code, network: .network.category}'

# Risk score and recommended action
curl -s https://api.ipbot.com/v1/ip/8.8.8.8 \
  | jq '{risk_score: .score.risk_score, action: .score.recommended_action}'

# Public signal labels
curl -s https://api.ipbot.com/v1/ip/8.8.8.8 \
  | jq -r '.evidence.signals[].label'

Pro RDAP Contacts

curl -s "https://api.ipbot.com/v1/ip/8.8.8.8?include=rdap_contacts&fields=ip,rdap" \
  -H "X-API-Key: $IPBOT_PRO_API_KEY" | jq

JavaScript / TypeScript

Repo-local starter: clients/javascript/ipbot-client.mjs.

import { IPBotClient } from "./clients/javascript/ipbot-client.mjs";

const ipbot = new IPBotClient({ apiKey: process.env.IPBOT_API_KEY });
const data = await ipbot.lookup("8.8.8.8", {
  fields: ["ip", "location", "score"],
});

console.log(data.score.risk_score);

const rdap = await ipbot.lookup("8.8.8.8", {
  include: ["rdap_contacts"],
  fields: ["ip", "rdap"],
});

console.log(rdap.rdap.contacts);

Basic Fetch

const response = await fetch("https://api.ipbot.com/v1/ip/8.8.8.8");
const data = await response.json();

console.log(data.network.category);
console.log(data.score.verdict);
console.log(data.evidence.signals.map((signal) => signal.label));

Typed Helper

type IPBotSignal = {
  category: string;
  label: string;
  severity: "info" | "low" | "medium" | "high";
  confidence: "low" | "medium" | "high";
  description?: string;
};

type IPBotResponse = {
  ip: string;
  score: {
    risk_score: number;
    verdict: "allow" | "monitor" | "challenge" | "block";
    recommended_action: "allow" | "rate_limit" | "captcha_challenge" | "manual_review" | "block";
  };
  network: {
    category: string;
    operator?: string;
    service_role?: string;
    service_name?: string;
    routability?: "global" | "private" | "non_global" | "reserved" | "bogon";
  };
  classification: {
    is_proxy: boolean;
    is_vpn: boolean;
    is_tor: boolean;
    is_datacenter: boolean;
    is_privacy_relay: boolean;
    is_public_resolver?: boolean;
    is_anycast?: boolean;
    is_special_use?: boolean;
    special_use_type?: string;
    is_bogon?: boolean;
    confidence: "low" | "medium" | "high";
    traits: string[];
  };
  evidence: {
    signals: IPBotSignal[];
  };
};

async function lookupIP(ip: string, apiKey?: string): Promise<IPBotResponse> {
  const response = await fetch(`https://api.ipbot.com/v1/ip/${ip}`, {
    headers: apiKey ? { "X-API-Key": apiKey } : {},
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.code}: ${error.error}`);
  }

  return response.json();
}

Risk Helper

function assessRisk(data) {
  const labels = data.evidence.signals.map((signal) => signal.label);

  return {
    ip: data.ip,
    riskScore: data.score.risk_score,
    verdict: data.score.verdict,
    recommendedAction: data.score.recommended_action,
    traits: data.classification.traits,
    signals: labels,
    needsFriction: ["challenge", "block"].includes(data.score.verdict),
  };
}

Python

Repo-local starter: clients/python/ipbot_client.py.

from ipbot_client import IPBotClient

client = IPBotClient()
data = client.lookup("8.8.8.8", fields=["ip", "location", "score"])

print(data["score"]["risk_score"])

rdap = client.lookup(
    "8.8.8.8",
    include=["rdap_contacts"],
    fields=["ip", "rdap"],
)

print(rdap["rdap"]["contacts"])

Basic Request

import requests

response = requests.get("https://api.ipbot.com/v1/ip/8.8.8.8")
response.raise_for_status()
data = response.json()

print(data["network"]["category"])
print(data["score"]["recommended_action"])
print([signal["label"] for signal in data["evidence"]["signals"]])

Reusable Client

import os
import requests

class IPBotClient:
    def __init__(self, api_key: str | None = None):
        self.session = requests.Session()
        if api_key:
            self.session.headers.update({"X-API-Key": api_key})

    def lookup(self, ip: str) -> dict:
        response = self.session.get(f"https://api.ipbot.com/v1/ip/{ip}", timeout=5)
        response.raise_for_status()
        return response.json()

    def assess(self, ip: str) -> dict:
        data = self.lookup(ip)
        return {
            "ip": data["ip"],
            "risk_score": data["score"]["risk_score"],
            "verdict": data["score"]["verdict"],
            "recommended_action": data["score"]["recommended_action"],
            "signals": [signal["label"] for signal in data["evidence"]["signals"]],
            "traits": data["classification"]["traits"],
        }

client = IPBotClient(os.getenv("IPBOT_API_KEY"))
print(client.assess("8.8.8.8"))

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type IPBotResponse struct {
    IP    string `json:"ip"`
    Score struct {
        RiskScore         int    `json:"risk_score"`
        Verdict           string `json:"verdict"`
        RecommendedAction string `json:"recommended_action"`
    } `json:"score"`
    Network struct {
        ASN      string `json:"asn"`
        Org      string `json:"org"`
        Category string `json:"category"`
        Operator string `json:"operator"`
        ServiceRole string `json:"service_role"`
        ServiceName string `json:"service_name"`
        Routability string `json:"routability"`
    } `json:"network"`
    Classification struct {
        IsProxy      bool     `json:"is_proxy"`
        IsDatacenter bool     `json:"is_datacenter"`
        IsPublicResolver bool `json:"is_public_resolver"`
        IsAnycast    bool     `json:"is_anycast"`
        IsSpecialUse bool     `json:"is_special_use"`
        SpecialUseType string `json:"special_use_type"`
        IsBogon     bool     `json:"is_bogon"`
        Confidence   string   `json:"confidence"`
        Traits       []string `json:"traits"`
    } `json:"classification"`
    Evidence struct {
        Signals []struct {
            Category   string `json:"category"`
            Label      string `json:"label"`
            Severity   string `json:"severity"`
            Confidence string `json:"confidence"`
        } `json:"signals"`
    } `json:"evidence"`
}

func LookupIP(ip string) (*IPBotResponse, error) {
    resp, err := http.Get("https://api.ipbot.com/v1/ip/" + ip)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var data IPBotResponse
    if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
        return nil, err
    }
    return &data, nil
}

func main() {
    data, err := LookupIP("8.8.8.8")
    if err != nil {
        panic(err)
    }
    fmt.Printf("%s %s risk=%d action=%s\n",
        data.IP, data.Network.Category, data.Score.RiskScore, data.Score.RecommendedAction)
}

PHP

<?php

function lookupIP(string $ip, ?string $apiKey = null): array {
    $headers = $apiKey ? ["X-API-Key: {$apiKey}"] : [];

    $ch = curl_init("https://api.ipbot.com/v1/ip/{$ip}");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => $headers,
    ]);

    $body = curl_exec($ch);
    curl_close($ch);

    return json_decode($body, true);
}

$data = lookupIP("8.8.8.8", getenv("IPBOT_API_KEY") ?: null);
echo "Risk: " . $data["score"]["risk_score"] . PHP_EOL;
echo "Action: " . $data["score"]["recommended_action"] . PHP_EOL;

Ruby

require "net/http"
require "json"

def lookup_ip(ip, api_key: nil)
  uri = URI("https://api.ipbot.com/v1/ip/#{ip}")
  request = Net::HTTP::Get.new(uri)
  request["X-API-Key"] = api_key if api_key

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  JSON.parse(response.body)
end

data = lookup_ip("8.8.8.8", api_key: ENV["IPBOT_API_KEY"])
puts data.dig("score", "recommended_action")