Quickstart Guide - Get Started with IPBot API in 30 Seconds

Base URL

Use the public API:

https://api.ipbot.com

Your First Request

cURL

Lookup a specific IPv4/IPv6 address:

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

Auto-detect the caller IP:

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

JavaScript

// Lookup a specific IP
const response = await fetch("https://api.ipbot.com/8.8.8.8");
const data = await response.json();
console.log(data);

// Auto-detect caller IP
const myIP = await fetch("https://api.ipbot.com/");
const myData = await myIP.json();
console.log(myData.ip);

Python

import requests

# Lookup a specific IP
response = requests.get('https://api.ipbot.com/8.8.8.8')
data = response.json()
print(data)

# Auto-detect caller IP
response = requests.get('https://api.ipbot.com/')
data = response.json()
print(data['ip'])

Go

package main

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

type IPBotResponse struct {
    IP string `json:"ip"`
    // Add other fields as needed
}

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

    body, _ := io.ReadAll(resp.Body)
    var data IPBotResponse
    json.Unmarshal(body, &data)
    fmt.Println(data.IP)
}

Common Use Cases

Get Country Code Only

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

Check if IP is a Datacenter

curl -s https://api.ipbot.com/8.8.8.8 | jq -r '.security.is_datacenter'

Get Risk Score

curl -s https://api.ipbot.com/8.8.8.8 | jq -r '.security.risk_score'

Get All Threat Lists

curl -s https://api.ipbot.com/8.8.8.8 | jq -r '.security.threat_lists[]'

Get an API Key (Higher Limits)

Anonymous access is rate-limited to 60 requests per minute. Sign in with GitHub to get a free API key with 200 req/min:

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_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  https://api.ipbot.com/8.8.8.8

Rate Limit Tiers

Tier	Rate Limit	How to Get
Anonymous	60 req/min	No authentication required
Free	200 req/min	Sign in with GitHub at /login
Pro	600 req/min	Contact us for enterprise access

Best Practices

Caching

IP geolocation data changes infrequently. Implement caching to reduce API calls and improve performance:

• Cache residential ISP results: 7-30 days
• Cache datacenter/VPN results: 1-7 days
• Cache mobile IP results: 1-7 days

Error Handling

Always check for error responses:

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

if (data.error) {
  console.error(`Error ${data.code}: ${data.error}`);
  // Handle error appropriately
  return;
}

// Process successful response
console.log(data.location.country);

Rate Limiting

Be respectful of the public API. Implement exponential backoff if you encounter rate limits:

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/{ip}')
        if response.status_code == 429:
            wait_time = 2 ** attempt
            time.sleep(wait_time)
            continue
        return response.json()
    return None

Troubleshooting

Issue: “Invalid IP address” error

Solution: Ensure you’re passing a valid IPv4 or IPv6 address. Check for typos or extra characters.

# Correct
curl https://api.ipbot.com/8.8.8.8

# Incorrect
curl https://api.ipbot.com/8.8.8.8.1

Issue: Empty location fields

Solution: Some IP addresses (especially private IPs) may not have complete location data. This is expected behavior.

Issue: Slow response times

Solution: The API typically responds in under 50ms. If you experience slowness:

1. Check your network connectivity
2. Verify DNS resolution for api.ipbot.com
3. Consider implementing client-side caching

Issue: CORS errors in browser

Solution: IPBot supports CORS for all origins. If you still see CORS errors:

1. Ensure you’re using HTTPS
2. Check for ad-blockers or browser extensions interfering
3. Verify your server-side proxy configuration

Next Steps

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

Local Development

This repo includes a Go API (default: http://localhost:8080) and a static frontend.

Backend

From the repository root:

make init
make up

Frontend

From web/:

npm install
npm run dev

To force the frontend demo to use your local API, set:

PUBLIC_IPBOT_API_ORIGIN=http://localhost:8080