Look up the address the call came from

GET/api/v1/ip/me

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

Runs the standard lookup for the address your request arrived from, as seen through the trusted proxy in front of the service. Useful from a server to confirm what the outside world sees, and from scripts that need their own egress classified. A reserved address, such as a call from the same machine, answers reason: "reserved_range" free of charge. browser_timezone and fields ride in the query string, and the answer carries Cache-Control: private, max-age=300.

Parameters

name	in	type	description
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.
browser_timezone	query	string	The IANA zone the browser reported to your page, compared with the located zone for timezone_matches; a zone the server does not know answers 422. At most 64 characters.
fields	query	string	A comma-separated list of the fields to answer with; unknown names are ignored and sources is included only if named. At most 1,000 characters.

Example request

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

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

import requests

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

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

from spaw import Client

client = Client('sk_live_…')
result = client.lookup_my_ip()

import Spaw from 'spaw';

const spaw = new Spaw({ apiKey: 'sk_live_…' });
const result = await spaw.lookupMyIp();

use Spaw\Client;

$spaw = new Client('sk_live_…');
$result = $spaw->lookupMyIp();

This endpoint has no console on its page. It answers about whichever address the call came from, so run from this page it would report your browser rather than the server you are going to call it from. POST /api/v1/ip takes an address and is runnable.

Responses

200The same body as `POST /api/v1/ip`, for the calling address.

{
    "success": true,
    "data": {
        "ip": "203.0.113.9",
        "version": 4,
        "reason": null,
        "country": "DE",
        "city": "Berlin",
        "is_datacenter": false,
        "risk_score": 0,
        "risk_level": "low"
    },
    "meta": {
        "credits_used": 0,
        "credits_remaining": 8,
        "cache_hit": false,
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c",
        "ip_lookups_prepaid": 3
    }
}

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