Docs / API reference

IP Geolocation

Returns the location, network, timezone, currency and security profile of the visitor who is calling your API.

Overview#

geoip answers the question "who is on the other end of this connection?" without you having to pass an address. Gurdx reads the IP of the request and enriches it with geography (continent, country, region, city, coordinates, flag, capital, languages), the owning network (ASN), local time and sunrise/sunset data, currency, and optional security and device modules.

When to use it#

Call it from the visitor's own browser or app to pre-fill a country or currency selector.
Gate or localize a signup flow based on where the user really is.
Flag a session that arrives through a proxy, VPN, Tor or hosting provider.

If you need to check an address that is not the caller's, for example one stored in your database or read from a header on your server, use IP Lookup.

Choosing what you receive#

By default you get the full response. Pass params to ask only for the modules you need: security, currency, timezone, location and device. Smaller responses are faster; see Customize modules. The device module parses the user agent of the request, so it is only meaningful when the call comes from the end user's own client.

Reading the result#

security.isProxy is true for anonymizing infrastructure, and security.proxyType tells you which kind (for example a VPN, a SOCKS proxy or a public proxy). Treat this as a signal to step up verification, not as proof of fraud: many honest users run VPNs.
security.isTor, security.isBot, security.isRelay and security.isHosting flag exit nodes, automated traffic, privacy relays and data-center ranges.
security.blacklisted is true when the IP matches one of your own blacklists.
bogon marks private or unroutable addresses, which usually means your server saw an internal proxy address instead of the visitor.

Notes#

Counts as one request. In mode=test or with a gx_test_ key you receive fake data and nothing is billed.
Available on every plan. The security and device modules require the security_module and device_module features; without them you get error 114.
With custom rules enabled on your plan, custom rules can blacklist or whitelist the IP; the outcome appears in custom_rules_applied.
A suspicious_ip event is raised when the computed risk reaches 50 out of 100, and is delivered to your webhooks.
Behind a reverse proxy, make sure the caller's real address, not your proxy's, reaches Gurdx.

Request#

GET https://gurdx.cretip.com/api/geoip

Authenticate with the key parameter or an Authorization: Bearer header.
Counts as 1 request.
Available on: Free trial Standard Premium Pay-as-you-go

Parameters#

Name	Type	Description
`params` optional query	`string`	The params command can be used to specify the required modules you want to get in the response. Expected values: `security`, `currency`, `timezone`, `location`, and/or `device` Sample value: `security,timezone,currency` For more information please refer to Customize response modules.

Every method also accepts format, lang, mode, userID, callback. See Options.

Code samples#

curl -G "https://gurdx.cretip.com/api/geoip" \
  --data-urlencode "key=YOUR_API_KEY"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/geoip?'.http_build_query(['key' => 'YOUR_API_KEY']));
$result = json_decode($response, true);

if ($result['status'] === 'success') {
    print_r($result['data']);
} else {
    echo $result['code'].': '.$result['description'];
}

const params = new URLSearchParams({"key":"YOUR_API_KEY"});
const res = await fetch(`https://gurdx.cretip.com/api/geoip?${params}`);
const result = await res.json();

if (result.status === 'success') {
  console.log(result.data);
} else {
  console.error(result.code, result.description);
}

import requests

res = requests.get("https://gurdx.cretip.com/api/geoip", params={"key": "YOUR_API_KEY"})
result = res.json()

if result["status"] == "success":
    print(result["data"])
else:
    print(result["code"], result["description"])

Response#

Success#

{
    "data": {
        "ip": "165.227.149.217",
        "ipType": "IPv4",
        "IPNumber": 2783155673,
        "bogon": false,
        "continentName": "Europe",
        "continentCode": "EU",
        "countryCode": "DE",
        "continentGeoNameID": 6255148,
        "countryName": "Germany",
        "countryGeoNameID": 2921044,
        "regionName": "Hessen",
        "cityName": "Frankfurt am Main",
        "zipCode": "65931",
        "latitude": "50.115520",
        "longitude": "8.684170",
        "location": {
            "capital": "Berlin",
            "population": 83783942,
            "language": {
                "name": "German",
                "code": "de",
                "native": "Deutsch"
            },
            "flag": {
                "emoji": "🇩🇪",
                "unicode": "U+1F1E9 U+1F1EA",
                "png": {
                    "1000px": "https://gurdx.cretip.com/flags/png1000px/de.png",
                    "250px": "https://gurdx.cretip.com/flags/png250px/de.png",
                    "100px": "https://gurdx.cretip.com/flags/png100px/de.png"
                },
                "svg": "https://gurdx.cretip.com/flags/svg/de.svg"
            },
            "phoneCode": "49",
            "countryIsEU": true,
            "countryNeighbours": "CH,PL,NL,DK,BE,CZ,LU,FR,AT",
            "tld": ".de"
        },
        "currency": {
            "currencyName": "Euro",
            "currencyCode": "EUR",
            "currencySymbol": "€"
        },
        "asn": {
            "asn": "AS14061",
            "name": "DIGITALOCEAN-ASN",
            "org": "DigitalOcean, LLC",
            "phone": "+1-347-875-6044",
            "email": "noc@digitalocean.com",
            "domain": "digitalocean.com",
            "created": "2012-05-14",
            "type": "hosting"
        },
        "timezone": {
            "name": "Europe/Berlin",
            "abbreviation": "CET",
            "offset": 3600,
            "currentTime": "03:33:13",
            "currentTimestamp": 1709519593,
            "isDST": false,
            "sunInfo": {
                "sunset": "18:14:11",
                "sunrise": "06:59:29",
                "transit": "12:36:50",
                "civilTwilightBegin": "06:28:47",
                "civilTwilightEnd": "18:44:53",
                "nauticalTwilightBegin": "05:51:20",
                "nauticalTwilightEnd": "19:22:21",
                "astronomicalTwilightBegin": "05:13:27",
                "astronomicalTwilightEnd": "20:00:13",
                "dayLength": "11:14:42"
            }
        },
        "security": {
            "isProxy": true,
            "proxyType": "VPN",
            "isTor": false,
            "isBot": false,
            "isRelay": false,
            "isHosting": true,
            "blacklisted": false
        },
        "device": {
            "isMobile": false,
            "type": "desktop",
            "OS": {
                "type": "desktop",
                "name": "MacOS",
                "family": "macintosh",
                "version": "Big Sur",
                "title": "MacOS Big Sur",
                "64bits_mode": 1
            },
            "browser": {
                "name": "Safari",
                "version": 17.2,
                "versionMajor": 1,
                "title": "Safari 17.2"
            }
        },
        "custom_rules_applied": {
            "total": 0,
            "rules": []
        }
    },
    "status": "success",
    "executionTime": 4
}

Error#

Errors are delivered with HTTP 200 — always check the status field.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

Response fields#

Name	Type	Description
`data.ip`	`string`	IP address you're looking up.
`data.ipType`	`string`	Type of IP address (`IPv4`, or `IPv6`).
`data.IPNumber`	`integer`	Numeric representation of the IP address.
`data.bogon`	`boolean`	Indicates if the IP address is a bogon.
`data.continentName`	`string`	Name of the continent where the IP address is.
`data.continentCode`	`string`	Code representation of the continent.
`data.countryCode`	`string`	Code representation of the country in `ISO-3166` format.
`data.continentGeoNameID`	`integer`	GeoName ID of the continent.
`data.countryName`	`string`	Name of the country.
`data.countryGeoNameID`	`integer`	GeoName ID of the country.
`data.regionName`	`string`	Name of the region.
`data.cityName`	`string`	Name of the city.
`data.zipCode`	`string`	ZIP code of the location where the IP address belong.
`data.latitude`	`string`	Latitude coordinate of the location.
`data.longitude`	`string`	Longitude coordinate of the location.
`data.location.capital`	`string`	Capital city of the country.
`data.location.population`	`integer`	Population of the country.
`data.location.language.name`	`string`	Official language of the country.
`data.location.language.code`	`string`	Language code in `ISO-639` format.
`data.location.language.native`	`string`	Native name of the language.
`data.location.language`	`object`	—
`data.location.flag.emoji`	`string`	Flag emoji representation.
`data.location.flag.unicode`	`string`	Flag Unicode representation.
`data.location.flag.png.1000px`	`string`	URL to 1000px PNG flag.
`data.location.flag.png.250px`	`string`	URL to 250px PNG flag.
`data.location.flag.png.100px`	`string`	URL to 100px PNG flag.
`data.location.flag.png`	`object`	—
`data.location.flag.svg`	`string`	URL to SVG flag.
`data.location.flag`	`object`	—
`data.location.phoneCode`	`string`	International dialing code for the country.
`data.location.countryIsEU`	`boolean`	Indicates if the country is in the EU.
`data.location.countryNeighbours`	`string`	List of neighboring countries' codes.
`data.location.tld`	`string`	Top-level domain of the country.
`data.location`	`object`	—
`data.currency.currencyName`	`string`	Name of the currency.
`data.currency.currencyCode`	`string`	Currency code in `ISO-4217` format.
`data.currency.currencySymbol`	`string`	Symbol of the currency.
`data.currency`	`object`	—
`data.asn.asn`	`string`	Autonomous System Number.
`data.asn.name`	`string`	Name of the ASN.
`data.asn.org`	`string`	Organization associated with the ASN.
`data.asn.phone`	`string`	Phone contact for the ASN.
`data.asn.email`	`string`	Email contact for the ASN.
`data.asn.domain`	`string`	Domain associated with the ASN.
`data.asn.created`	`string`	Date of ASN creation.
`data.asn.type`	`string`	Type of organization ("isp", "hosting", "business", "education", or "government").
`data.asn`	`object`	—
`data.timezone.name`	`string`	Timezone name.
`data.timezone.abbreviation`	`string`	Timezone abbreviation.
`data.timezone.offset`	`integer`	Timezone offset from UTC.
`data.timezone.currentTime`	`string`	Current time in the timezone.
`data.timezone.currentTimestamp`	`integer`	Current timestamp in the timezone.
`data.timezone.isDST`	`boolean`	Indicates if Daylight Saving Time is active.
`data.timezone.sunInfo.sunset`	`string`	Sunset time.
`data.timezone.sunInfo.sunrise`	`string`	Sunrise time.
`data.timezone.sunInfo.transit`	`string`	Solar transit time.
`data.timezone.sunInfo.civilTwilightBegin`	`string`	Civil twilight begin time.
`data.timezone.sunInfo.civilTwilightEnd`	`string`	Civil twilight end time.
`data.timezone.sunInfo.nauticalTwilightBegin`	`string`	Nautical twilight begin time.
`data.timezone.sunInfo.nauticalTwilightEnd`	`string`	Nautical twilight end time.
`data.timezone.sunInfo.astronomicalTwilightBegin`	`string`	Astronomical twilight begin time.
`data.timezone.sunInfo.astronomicalTwilightEnd`	`string`	Astronomical twilight end time.
`data.timezone.sunInfo.dayLength`	`string`	Length of the day.
`data.timezone.sunInfo`	`object`	—
`data.timezone`	`object`	—
`data.security.isProxy`	`boolean`	Indicates if the IP address is a proxy service.
`data.security.proxyType`	`string`	Type of proxy used.
`data.security.isTor`	`boolean`	Indicates if accessed through Tor network.
`data.security.isBot`	`boolean`	Indicates if the user is a bot.
`data.security.isRelay`	`boolean`	Indicates if it's a Apple's Private Relay connection.
`data.security.isHosting`	`boolean`	Indicates if the IP address belong to a hosting provider.
`data.security.blacklisted`	`boolean`	Indicates if the IP address is blacklisted due to applying custom rules or were found in one of your blacklists.
`data.security`	`object`	—
`data.device.isMobile`	`boolean`	Indicates if the device is a mobile device.
`data.device.type`	`string`	Type of device.
`data.device.OS.type`	`string`	Type of operating system.
`data.device.OS.name`	`string`	Name of the operating system.
`data.device.OS.family`	`string`	Family of the operating system.
`data.device.OS.version`	`string`	Version of the operating system.
`data.device.OS.title`	`string`	Title of the operating system.
`data.device.OS.64bits_mode`	`integer`	Indicates 64-bit mode (1 for true, 0 for false).
`data.device.OS`	`object`	—
`data.device.browser.name`	`string`	Name of the browser.
`data.device.browser.version`	`number`	Version of the browser.
`data.device.browser.versionMajor`	`integer`	Major version of the browser.
`data.device.browser.title`	`string`	Title of the browser.
`data.device.browser.userAgent`	`string`	The user-agent of the browser.
`data.device.browser`	`object`	—
`data.device`	`object`	—
`data.custom_rules_applied.total`	`integer`	The total number of custom rules applied to this request.
`data.custom_rules_applied.rules.id`	`string`	The rule ID as shown in the dashboard (e.g: `CR104`).
`data.custom_rules_applied.rules.title`	`string`	The rule title you set when creating the rule.
`data.custom_rules_applied.rules`	`object`	The custom rules applied to this request, learn more.
`data.custom_rules_applied`	`object`	The custom rules applied to this request, learn more.
`data.status`	`string`	Response status (success/error).
`data.executionTime`	`integer`	Time taken to process the data (in milliseconds).
`data`	`object`	—

Found a mistake? Tell us on the contact page. Contact