Docs / API reference

IP Lookup

Looks up any IPv4 or IPv6 address and returns its geography, network owner, timezone, currency and security flags.

Overview#

lookup/ip is the server-side counterpart of IP Geolocation. Instead of reading the caller's address, you pass the one you care about in the ip parameter. The response has the same structure: location, asn, timezone, currency, and a security block describing proxy, Tor, bot, relay and hosting traffic.

When to use it#

Check the address recorded at signup, login or checkout, from your backend.
Enrich an audit log or support ticket with the user's country and network.
Re-evaluate addresses already stored in your system.

For many addresses at once, see Bulk IP Lookup. For threat flags only, with a smaller payload, see IP Reputation.

Reading the result#

security.isProxy and security.proxyType show whether the address belongs to a VPN, proxy or similar service and of what kind. A proxy alone is a weak signal; combine it with other evidence such as a country mismatch with the billing address.
security.isHosting is a strong hint of automation, since real customers rarely browse from data-center ranges. isTor and isBot are stronger still.
security.blacklisted reflects your own blacklists. When a rule or a blacklist entry matches, the security.custom_rules_applied block lists what fired.
zipCode is the postal code of the location. It is matched on the city name, else on the nearest postal point within about 25 km, so it is an approximation of the area, not of a street. It is null where no postal data exists (for example most of Saudi Arabia, Egypt and the UAE).
asn.email and asn.phone are the contact published in the network's registry record, preferring the abuse and technical contacts. They are null when the registry publishes none or is unreachable.
bogon: true means a private or reserved address. Gurdx cannot place it geographically, so verify which address your server forwards.
Use params to request only some modules; see Customize modules.

Notes#

One request per call. Test mode (mode=test or a gx_test_ key) returns fake data, is free and never raises events.
Included in every plan. The security and device modules need the matching plan features.
Custom rules for the IP group can test the country, continent, region, city, ASN and each security flag, and can add the address to a blacklist or whitelist.
A suspicious_ip event is raised when the risk reaches 50 out of 100 and is sent to your webhooks.
An empty or malformed address returns error 112 (invalid_ip) with HTTP 200.

Request#

GET https://gurdx.cretip.com/api/lookup/ip

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
`ip` required query	`string`	The ip command is used to specify the IP address you want to lookup. Expected values: an IP address (IPv4 or IPv6) Sample value: `1.1.1.1`
`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`, and/or `location`. 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/lookup/ip" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "ip=1.1.1.1"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/lookup/ip?'.http_build_query(['key' => 'YOUR_API_KEY', 'ip' => '1.1.1.1']));
$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","ip":"1.1.1.1"});
const res = await fetch(`https://gurdx.cretip.com/api/lookup/ip?${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/lookup/ip", params={"key": "YOUR_API_KEY", "ip": "1.1.1.1"})
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
        },
        "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.custom_rules_applied.total`	`integer`	The total number of custom rules applied to this request.
`data.security.custom_rules_applied.rules.id`	`string`	The rule ID as shown in the dashboard (e.g: `CR104`).
`data.security.custom_rules_applied.rules.title`	`string`	The rule title you set when creating the rule.
`data.security.custom_rules_applied.rules`	`object`	The custom rules applied to this request, learn more.
`data.security.custom_rules_applied`	`object`	The custom rules applied to this request, learn more.
`data.security`	`object`	—
`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