Docs / API reference

Bulk IP Lookup

Checks several IP addresses in a single call and returns a full lookup result for each one.

Overview#

lookup/ip/bulk takes a comma-separated list of IPv4 and/or IPv6 addresses in the ips parameter, for example 1.1.1.1,2.2.2.2, and returns the same enrichment you would get from IP Lookup for each address: geography, network, timezone, currency and security flags. Send a comma-separated list (up to 50 per request).

When to use it#

Back-filling or re-scoring a table of stored addresses.
Reviewing the IPs in a batch of orders or sessions in one pass.
Cutting round trips when a single user action involves several addresses, such as the connection IP and a forwarded IP.

For a single address, IP Lookup is simpler and keeps the response flat.

Reading the result#

The data element holds one entry per address you sent, each shaped like a standard lookup. Read each entry independently:

security.isProxy with security.proxyType tells you whether and how the address is anonymized.
security.isHosting, isTor and isBot point to automation.
security.blacklisted shows a match against your own blacklists.

Keep your own record of which input produced which entry, and remember that duplicate or malformed values in the list may fail the whole call with error 112 (invalid_ip), so clean the list before sending it.

Notes#

Billed as a single API request per call. Test mode returns fake data, is free and raises no events.
Included in every plan, with the security and device modules subject to your plan features.
The same custom rules and blacklists used for single lookups are applied to every address.
Events of type suspicious_ip are raised at a risk of 50 or more out of 100 and delivered to your webhooks.
Use params to trim the modules and keep large batches fast; see Customize modules.

Request#

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

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

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/lookup/ip/bulk?'.http_build_query(['key' => 'YOUR_API_KEY', 'ips' => '1.1.1.1,8.8.8.8']));
$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","ips":"1.1.1.1,8.8.8.8"});
const res = await fetch(`https://gurdx.cretip.com/api/lookup/ip/bulk?${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/bulk", params={"key": "YOUR_API_KEY", "ips": "1.1.1.1,8.8.8.8"})
result = res.json()

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

Response#

Success#

{
    "data": {
        "1.1.1.1": {
            "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": []
            }
        },
        "8.8.8.8": {
            "ip": "8.8.8.8",
            "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": 9
}

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."
}

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