🌍 IP Detector

IP Detector

One internal endpoint that turns an IP address into a country, city, timezone and currency — so every one of your projects answers "where is this visitor?" the same way.

You are calling from 216.73.216.156.

Authentication

Two ways in, checked in this order:

  1. Whitelisted IP — servers on the whitelist call the API with no credential at all.
  2. 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://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://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://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

FieldDescription
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://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;