Quickstart Guide - Get Started with IPBot API in 30 Seconds

Base URL

Use the public v1 API:

https://api.ipbot.com/v1

Your First Request

cURL

Lookup a specific IPv4/IPv6 address:

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

Auto-detect the caller IP:

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

JavaScript

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

console.log(data.score.risk_score);
console.log(data.score.recommended_action);
console.log(data.evidence.signals.map((signal) => signal.label));

Python

import requests

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

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

Go

package main

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

type IPBotResponse struct {
    IP    string `json:"ip"`
    Score struct {
        RiskScore         int    `json:"risk_score"`
        RecommendedAction string `json:"recommended_action"`
    } `json:"score"`
    Classification struct {
        IsDatacenter bool     `json:"is_datacenter"`
        IsProxy      bool     `json:"is_proxy"`
        Traits       []string `json:"traits"`
    } `json:"classification"`
}

func main() {
    resp, err := http.Get("https://api.ipbot.com/v1/ip/8.8.8.8")
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

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

    fmt.Printf("%s risk=%d action=%s\n", data.IP, data.Score.RiskScore, data.Score.RecommendedAction)
}

Common Use Cases

Get Country Code

curl -s https://api.ipbot.com/v1/ip/8.8.8.8 | jq -r '.location.country_code'

Check Network Category

curl -s https://api.ipbot.com/v1/ip/8.8.8.8 | jq -r '.network.category'

Get Risk Score And Action

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

List Public Signals

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

Get an API Key

Anonymous access is rate-limited. Sign in with GitHub to get a free API key with higher limits:

1. Visit ipbot.com/login and sign in with GitHub
2. Access your Dashboard to view your API key
3. Use the key in your requests:

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

Best Practices

Caching

IP intelligence changes at different speeds by class:

• Cache residential ISP results: 7-30 days
• Cache datacenter, proxy, or VPN results: 1-7 days
• Cache mobile IP results: 1-7 days

Error Handling

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

if (!response.ok || data.error) {
  console.error(`Error ${data.code}: ${data.error}`);
  return;
}

console.log(data.score.verdict);

Rate Limiting

import time
import requests

def get_ip_info(ip, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(f"https://api.ipbot.com/v1/ip/{ip}")
        if response.status_code == 429:
            time.sleep(2 ** attempt)
            continue
        return response.json()
    return None

Troubleshooting

Issue: “Invalid IP address” error

Ensure you’re passing a valid IPv4 or IPv6 address.

curl https://api.ipbot.com/v1/ip/8.8.8.8
curl https://api.ipbot.com/v1/ip/2001:4860:4860::8888

Issue: Empty location fields

Some IP addresses, especially private or reserved IPs, may not have complete location data.

Issue: Slow response times

Check your network, verify DNS resolution for api.ipbot.com, and cache repeat lookups where possible.

Next Steps

• Read the full API Reference
• Learn fields in the Response Schema
• Review caching guidance in Rate Limits
• Explore Integration Guides