Look up an address by path

GET/api/v1/ip/{ip}

authentication: Secret API key as a bearer token
billing: As `POST /api/v1/ip`.

Exactly POST /api/v1/ip with the address in the path and the options in the query string, for callers that prefer a plain GET: GET /api/v1/ip/8.8.8.8?privacy=1. The response, billing and rate limit are the same.

Parameters

name	in	type	description
iprequired	path	string	An IPv4 or IPv6 address.
privacy	query	boolean	Keep nothing about this lookup, not even the seven-day repeat marker.
abuse_contact	query	boolean	Also look up the network's abuse mailbox from the registry's RDAP record.
network_details	query	boolean	Also read the allocation's RDAP record for the network name, organisation, range and registration dates.
hostname	query	boolean	Also resolve and forward-confirm the reverse DNS name; a verified crawler name sets is_crawler.

Example request

curl https://spaw.co/api/v1/ip/8.8.8.8 \
  -H "Authorization: Bearer sk_live_…"

const response = await fetch('https://spaw.co/api/v1/ip/8.8.8.8', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_live_…',
  },
});
const result = await response.json();

import requests

response = requests.get(
    'https://spaw.co/api/v1/ip/8.8.8.8',
    headers={'Authorization': 'Bearer sk_live_…'},
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/ip/8.8.8.8');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…'],
]);
$result = json_decode(curl_exec($ch), true);

Responses

200The same body as `POST /api/v1/ip`.

{
    "success": true,
    "data": {
        "ip": "8.8.8.8",
        "version": 4,
        "reason": null,
        "country": "US",
        "city": "Mountain View",
        "is_datacenter": true,
        "risk_score": 40,
        "risk_level": "medium"
    },
    "meta": {
        "credits_used": 1,
        "credits_remaining": 8,
        "cache_hit": false,
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

401The key is missing, malformed, or revoked.

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

402The balance is empty. The lookup did not run.

{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

422The request body could not be validated; `error.errors` lists the fields.

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

429Over 5 requests per second for the key. Retry after the limit resets.

{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

Error codes

Failures answer { success: false, error: { code, message, request_id } }. Each code has its own page.

markdown version·openapi.json