API documentation — IP Detector

Authentication

Two ways in, checked in this order:

Whitelisted IP — servers on the whitelist call the API with no credential at all.
API key — everyone else sends a key. Any of these work:

X-API-Key: ipd_your_key_here
Authorization: Bearer ipd_your_key_here
?api_key=ipd_your_key_here

A missing or invalid credential returns 401; exceeding the rate limit returns 429 with a Retry-After header.

Endpoints

GET /api/v1/me

The caller's own address. This is the one most projects use.

curl https://www.ip.geexar.cloud/api/v1/me \
  -H "X-API-Key: ipd_your_key_here"

GET /api/v1/lookup/{ip}

Any address. Accepts IPv4 and IPv6.

curl https://www.ip.geexar.cloud/api/v1/lookup/8.8.8.8

GET /api/v1/country and /api/v1/country/{ip}

Country code only — the smallest payload, for redirect and tax logic.

{
    "ip": "8.8.8.8",
    "country_code": "US",
    "country_name": "United States",
    "found": true,
    "source": "maxmind",
    "cached": true
}

POST /api/v1/lookup/batch

Up to 100 addresses per call. Invalid entries come back as error rows instead of failing the batch.

curl -X POST https://www.ip.geexar.cloud/api/v1/lookup/batch \
  -H "X-API-Key: ipd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"]}'

GET /api/v1/countries

Reference list of every country the API can return, with currency and calling code.

GET /api/health no auth

Which sources are reachable and how old the local database is. Point a monitor at it.

maxmind ✓ ip-api ✓ ipwhois ✓ ipapi-co ✓

Trimming the response

Add ?fields= with a comma separated list to get back only what you need. ip and found are always included.

GET /api/v1/lookup/8.8.8.8?fields=country_code,city,currency_code

{
    "ip": "8.8.8.8",
    "found": true,
    "country_code": "US",
    "city": "Ashburn",
    "currency_code": "USD"
}

Response fields

Field	Description
ip	The address that was resolved.
found	False when no source could place the address.
country_code	ISO 3166-1 alpha-2, e.g. EG.
country_code_iso3	ISO 3166-1 alpha-3, e.g. EGY.
country_name	English country name.
country_flag	Flag emoji.
country_flag_url	PNG flag image, self-hosted from this server.
capital	Capital city.
is_eu	True for EU member states — useful for VAT and GDPR branching.
continent_code	AF, AN, AS, EU, NA, OC or SA.
region / region_code	State or province, when the city database or provider knows it.
city	City name.
postal_code	Postal code, where available.
latitude / longitude	Approximate coordinates.
accuracy_radius_km	MaxMind confidence radius around those coordinates.
timezone	IANA timezone, e.g. Africa/Cairo.
utc_offset	Current offset, e.g. +02:00.
local_time	Current time at that location, ISO 8601.
currency_code	ISO 4217 code, e.g. EGP.
currency_symbol	Display symbol for that currency.
calling_code	International dialling prefix, e.g. +20.
asn / organization / isp	Network operator, when the ASN database or provider supplies it.
is_proxy / is_hosting	Proxy and datacentre flags. Only some sources report these.
source	Which link in the chain answered: maxmind, ip-api, ipwhois, ipapi-co, ipinfo.
cached	True when served from the local cache.

Configuration

Administrators manage the MaxMind licence key, the ipinfo token, the fallback provider chain, cache lifetime, rate limits and log retention from the dashboard's Settings page. Changes take effect on the next request.

Using it from another Laravel project

Copy client/IpDetectorClient.php from this repository into your project — it has no dependencies beyond cURL and fails open, so a lookup outage never breaks a checkout.

$client = new IpDetectorClient('https://www.ip.geexar.cloud', 'ipd_your_key_here');

$country = $client->countryCode();          // "EG" for the current visitor
$location = $client->lookup('8.8.8.8');     // full payload
$isEu = $client->lookup()['is_eu'] ?? false;