NAV Navbar
cURL PHP Python Node.js Ruby IPFinder CLI

Getting started

The IPFINDER API is exposed via RESTful web services and makes use of the standard JSON encoding.

This geolocation API developer documentation will show you how to query.

Authentication

In order to fetch information about an IP address, you need to build a request URL of the following form :

# With token query parameter

$ curl -X GET https://api.ipfinder.io/v1/?token=$TOKEN

# With POST application/json

$ curl -d '{"token":"$TOKEN"}' -H "Content-Type: application/json" -X POST https://api.ipfinder.io/v1/

# With POST application/x-www-form-urlencoded

$ curl -d "token=$TOKEN" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://api.ipfinder.io/v1/

# With Basic Auth
$ curl -u $TOKEN: https://api.ipfinder.io/v1/

# With X-Authorization token
$ curl -H 'X-Authorization: $TOKEN' https://api.ipfinder.io/v1/
<?php
use ipfinder\ipfinder\IPfinder;

// Token
$client = new IPfinder('YOUR_TOKEN_GOES_HERE');


// lookup your IP address information

$details = $client->Authentication();

var_dump($details);

import ipfinder

config = ipfinder.config('YOUR_TOKEN_GOES_HERE')

# lookup your IP address information
auth = config.Authentication()

auth.details

const Ipfinder = require('ipfinder');
const ipfinder = new Ipfinder('YOUR_TOKEN_GOES_HERE');

ipfinder.Authentication().then(data => {
     console.log(data);
    // console.log(data.status_message);
}).catch(console.log);

require 'ipfinder'
config = Ipfinder::config('YOUR_TOKEN_GOES_HERE')

# lookup your IP address information
puts auth.inspect

puts auth.ip # your ip


  # shortopt
$ ipfinder -a
  # longopt
$ ipfinder --auth

Make sure to replace $TOKEN with your API key.

Your API token is used to authenicate you with our API, and can be provided either as a POST , Basic Auth OR X-Authorizatio, or alternatively as a token URL parameter.

Get IP address details

In order to fetch information about an IP address, you need to build a request URL of the following form :

Examples

# With GET Get details for 1.0.0.0
curl -X GET https://api.ipfinder.io/v1/1.0.0.0?token=$TOKEN

# With POST Get details for 1.0.0.0
curl -d '{"token":"$TOKEN"}' -X POST https://api.ipfinder.io/v1/1.0.0.0

# With X-Authorization token details for 1.0.0.0
curl  -H 'X-Authorization:$TOKEN' -X GET https://api.ipfinder.io/v1/1.0.0.0

# parameters Examples
# jsonp
curl -d '{"token":"$TOKEN", "format":"jsonp", "callback": "test"}' -H "Content-Type: application/json" -X POST https://api.ipfinder.io/v1/1.0.0.0


# xml 
curl -d '{"token":"$TOKEN", "format" : "xml"}' -H "Content-Type: application/json" -X POST https://api.ipfinder.io/v1/169.57.0.140


# php
curl -d '{"token":"$TOKEN", "format" : "php"}' -H "Content-Type: application/json" -X POST https://api.ipfinder.io/v1/169.57.0.140

<?php

use ipfinder\ipfinder\IPfinder;

// Token
$client = new IPfinder('YOUR_TOKEN_GOES_HERE');

// GET Get details for 1.0.0.0
$ip_address = '1.0.0.0';

// lookup IP address information

$details = $client->getAddressInfo($ip_address);

var_dump($details);
import ipfinder

config = ipfinder.config('YOUR_TOKEN_GOES_HERE')

# GET Get details for 1.0.0.0

ip = config.getAddressInfo('1.0.0.0')

ip.details
const Ipfinder = require("ipfinder");
const ipfinder = new Ipfinder();

ipfinder.getAddressInfo("1.0.0.0").then(data => {
     console.log(data);
    // console.log(data.status_message);
}).catch(console.log);
require 'ipfinder'
config = Ipfinder::config('YOUR_TOKEN_GOES_HERE')

# GET Get details for 1.0.0.0
ip_address = '1.0.0.0'

# lookup IP address information
ip = config.getAddressInfo('1.0.0.0')

puts ip.inspect


  # shortopt
$ ipfinder -i 5.5.5.5
  # longopt
$ ipfinder --ip 2.2.2.2

Here are a few examples for fetching IP address information from the command line :

HTTP Request

GET https://api.ipfinder.io/v1/{ipAddress}?token=$TOKEN

POST https://api.ipfinder.io/v1/{ipAddress}

The parameters are defined as follows :

Parameter Default Description
token Required Your API key or the string "free" for the free API
ipAddress Required The API supports passing in a single IPv4 or IPv6 IP address
format optional available format json jsonp php xml
callback optional add callback name if format equal jsonp
propertyName optional specify a single field name to request instead of the whole address details

Response Objects details

Depending on your subscription plan and the options you choose for your API request, the ipstack API will respond using a series of different modules and objects. Find below a list of all available API response objects explained.

Full Response

{
    "status": "ok",
    "status_message": "Query was successful",
    "ip": "169.57.0.140",
    "type": "IPV4",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code": "US",
    "country_name": "United States",
    "country_native_name": "United States",
    "region_name": "Minnesota",
    "city": "Rochester",
    "latitude": "44.0592",
    "longitude": "-92.5063",
    "location": {
        "capital": "Washington, D.C.",
        "country_flag": "http:\/\/fipfinder.io\/flag\/usa.svg",
        "flag_png": "http:\/\/fipfinder.io\/flag\/usa.png",
        "country_flag_emoji": "\ud83c\uddfa\ud83c\uddf8",
        "country_flag_emoji_unicode": "U+1F1FA U+1F1F8",
        "calling_code": "1",
        "toplevel_domain": ".us",
        "alpha3_code": "USA",
        "population": "321645000",
        "is_eu": false,
        "is_ar": false
    },
    "time_zone": {
        "id": "America\/New_York",
        "UTC": "UTC\u221212:00",
        "gmt_offset": -18000,
        "current_time": "2019-02-18 14:08:18"
    },
    "currency": {
        "name": "United States dollar",
        "symbol": "USD",
        "symbol_native": "$"
    },
    "languages": {
        "code": "en",
        "name": "English",
        "name_native": "English"
    },
    "connection": {
        "asn": "36351",
        "organization": "SoftLayer Technologies Inc.",
        "domain": "softlayer.com",
        "type": "Hosting"
    },
    "security": {
        "is_proxy": false,
        "proxy_type": false,
        "is_tor": false,
        "is_spam": false,
        "threat_level": "Low"
    },
    "header": {
        "total_user_agent": 8,
        "list_user_agent": [
            {
                "user_agent": "Mozilla\/5.0 (Windows NT 6.1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/41.0.2228.0 Safari\/537.36",
                "browser_name": "Chrome",
                "os_name": "Windows",
                "device_type": "desktop"
            },
            {
                "user_agent": "Mozilla\/5.0 (Linux; U; Android 4.0.4; en-us; Glass 1 Build\/IMM76L; XE10) AppleWebKit\/534.30 (KHTML, like Gecko) Version\/4.0 Mobile Safari\/534.30",
                "browser_name": null,
                "os_name": null,
                "device_type": "headset"
            },
            {
                "user_agent": "Mozilla\/5.0 (compatible; IBrowse 3.0; AmigaOS4.0)\r\n",
                "browser_name": "IBrowse",
                "os_name": "AmigaOS",
                "device_type": "desktop"
            },
            {
                "user_agent": "Mozilla\/5.0 (Linux; U; Android 2.1-update1; en-au; HTC_Desire_A8183 V1.16.841.1 Build\/ERE27) AppleWebKit\/530.17 (KHTML, like Gecko) Version\/4.0 Mobile Safari\/530.17",
                "browser_name": "Android Browser",
                "os_name": "Android",
                "device_type": "mobile"
            },
            {
                "user_agent": "Feed Viewer 3.9.3843.18128",
                "browser_name": null,
                "os_name": null,
                "device_type": ""
            },
            {
                "user_agent": "itunes\/9.0.2 (Macintosh; Intel Mac OS X 10.4.11) AppleWebKit\/531.21.8",
                "browser_name": null,
                "os_name": "OS X",
                "device_type": "desktop"
            },
            {
                "user_agent": "Mozilla\/5.0 (compatible; Googlebot\/2.1; +http:\/\/www.google.com\/bot.html)",
                "browser_name": "Googlebot",
                "os_name": null,
                "device_type": "bot"
            },
            {
                "user_agent": "Mozilla\/5.0 (X11; Linux x86_64) AppleWebKit\/535.2 (KHTML, like Gecko) Ubuntu\/11.04 Chromium\/15.0.871.0 Chrome\/15.0.871.0 Safari\/535.2",
                "browser_name": "Chromium",
                "os_name": "Ubuntu",
                "device_type": "desktop"
            }
        ]
    }
}
Response Object Description
ip Requested IP address
type IP address
continent_code 2-letter continent code
continent_name Continent name
country_code ISO 3166-1 alpha-2 country code
country_name Country name
country_native_name Country native name
region_name State or province name
city City name
latitude Decimal latitude
longitude Decimal longitude
location [Object] List of location raised by IP address
location->capital Returns the capital city of the country associated with the IP.
location->country_flag Returns an HTTP URL leading to an SVG-flag icon for the country associated with the IP.
location->flag_png Returns an HTTP URL leading to an PNG-flag icon for the country associated with the IP.
location->country_flag_emoji Returns the emoji icon for the flag of the country associated with the IP.
location->country_flag_emoji_unicode Returns the unicode value of the emoji icon for the flag of the country associated with the IP. (e.g. U+1F1F5 U+1F1F9 for the Portuguese flag)
location->calling_code Returns the calling/dial code of the country associated with the IP. (e.g. 351) for Portugal.
location->toplevel_domain Returns country domain name (e.g .dz .co )
location->alpha3_code ISO 3166-1 alpha-3 country code
location->population Country population
location->is_eu Returns true or false depending on whether or not the county associated with the IP is in the European Union.
location->is_ar Returns true or false depending on whether or not the county associated with the IP is in the ARABIC Union.
time_zone [Object] Returns an object containing timezone-related data.
time_zone->id Returns the ID of the time zone associated with the IP. (e.g. Australia/Lord_Howe for PST)
time_zone->UTC UTC
time_zone->gmt_offset Returns the GMT offset of the given time zone in seconds. (e.g. -25200 for PST's -7h GMT offset)
time_zone->current_time Returns the current date and time in the location associated with the IP. (e.g. 2019-02-19 06:58:25)
currency [Object] Returns an object containing currency-related data.
currency->name Returns the name of the given currency.
currency->symbol Returns the 3-letter code of the main currency associated with the IP.Example: USD
currency->symbol_native Returns the native symbol letter of the given currency .Example: $.
languages [Object] Returns an object containing one or multiple sub-objects per language spoken in the country associated with the IP.
languages->code Returns the 2-letter language code for the given language.
languages->name Returns the name (in the API request's main language) of the given language. (e.g. Arabic)
languages->name_native Returns the native name of the given language. (e.g. العربية)
connection [Object] Returns an object containing connection-related data.
connection->asn Returns the Autonomous System Number associated with the IP.
connection->organization Returns the name of the organization associated with the IP.
connection->domain Returns the name of the domain associated with the IP.
connection->type Returns the name of the type associated with the IP List of all available (isp, hosting, Business, Other).
security [Object] Returns an object containing security-related data.
security->is_proxy Returns true or false depending on whether or not the given IP is associated with a proxy.
security->proxy_type Returns the type of proxy the IP is associated with. List of all available(cgi, web, vpn)
security->is_tor Returns true or false depending on whether or not the given IP is associated with the anonymous Tor system.
security->is_spam Returns true or false depending on whether or not the given IP is associated with the spammer db .
security->threat_level Returns the type of threat level the IP is associated with. List of all available(low, medium, high)
header [Object] Returns an object containing header-related data.
header->total_user_agent Returns an number of User Agent associated with the IP.
header->list_user_agent [Object] Returns an object containing User Agent-related data(user_agent,browser_name,os_name,device_type).

Get AS details

Examples

Here are sample command lines for fetching API service information :

# With GET Get details for 1.0.0.0
curl -X GET https://api.ipfinder.io/v1/(asNumber)?token=$TOKEN

# With POST Get details for 1.0.0.0
curl -d '{"token":"$TOKEN"}' -H "Content-Type: application/json" -X POST https://api.ipfinder.io/v1/(asNumber)

# parameters Examples
# jsonp
curl -d '{"token":"$TOKEN", "format":"jsonp", "callback": "test"}' -H "Content-Type: application/json" -X POST https://api.ipfinder.io/v1/(asNumber)


# xml 
curl -d '{"token":"$TOKEN", "format" : "xml"}' -H "Content-Type: application/json" -X POST https://api.ipfinder.io/v1/(asNumber)


# php
curl -d '{"token":"$TOKEN", "format" : "php"}' -H "Content-Type: application/json" -X POST https://api.ipfinder.io/v1/(asNumber)

<?php
use ipfinder\ipfinder\IPfinder;

// Token
$client = new IPfinder('YOUR_TOKEN_GOES_HERE');

$asn = 'as36947';

// lookup Asn information
$details = $client->getAsn($asn);

var_dump($details);


// get and print continent name
echo $details->continent_name."\n";

// get and print speed
echo $details->speed['ping']."\n";

import ipfinder

config = ipfinder.config('YOUR_TOKEN_GOES_HERE')

# lookup Asn information
asn = config.getAsn('AS1')

asn.details
const Ipfinder = require('ipfinder');
const ipfinder = new Ipfinder('YOUR_TOKEN_GOES_HERE');

ipfinder.getAsn("as1").then(data => {
     console.log(data);
    // console.log(data.status_message);
}).catch(console.log);
require 'ipfinder'
config = Ipfinder::config('YOUR_TOKEN_GOES_HERE')

asn = 'as36947'

# lookup Asn information
asn = config.getAsn(asn)

puts asn.inspect


  # shortopt
$ ipfinder -n as1
  # longopt
$ ipfinder --asn as99

Make sure to replace Add (as|AS) to asNumber example as1 or AS1.

HTTP Request

GET https://api.ipfinder.io/v1/(as|AS){asNumber}?token=$TOKE

POST https://api.ipfinder.io/v1/as

The parameters are defined as follows :

Parameter Default Description
token Required Your API key or the string "free" for the free API
asNumber Required The AS number you want details for
format optional available format json jsonp php xml
callback optional add callback name if format equal jsonp
propertyName optional specify a single field name to request instead of the whole address details

Response object

Full Response

{
    "status": "ok",
    "status_message": "Query was successful",
    "asn": "AS36947",
    "org_name": "Telecom Algeria",
    "continent_code": "AF",
    "continent_name": "Africa",
    "country_code": "DZ",
    "country_name": "Algeria",
    "allocated": "2007-04-27",
    "registry": "afrinic",
    "domain": "algerietelecom.dz",
    "num_ips_ipv4": "4,353,792",
    "num_ips_ipv6": "79,228,162,514,264,337,593,543,950,336",
    "as_name": "ALGTEL-AS",
    "org_id": "ORG-TA23-AFRINIC",
    "comany_type": "isp",
    "speed": {
        "ping": "270.1 ms",
        "download": "10.97 ms",
        "upload": "0.79 ms"
    },
    "peers": {
        "total_peers": 4,
        "list_peers": [
            "AS12956",
            "AS174",
            "AS5511",
            "AS6762"
        ]
    },
    "upstreams": {
        "total_upstreams": 4,
        "list_upstreams": [
            "AS12956",
            "AS174",
            "AS5511",
            "AS6762"
        ]
    },
    "downstreams": {
        "total_downstreams": 3,
        "list_downstreams": [
            "AS327712",
            "AS327931",
            "AS33779"
        ]
    },
    "prefixes": {
        "total_prefixes": 261,
        "list_prefixes": [
            "41.96.0.0\/16",
            "41.96.0.0\/13",

        ]
    }
}
Response Object Description
asn AS number
org_name Organization name
continent_code 2-letter continent code
continent_name Continent name
country_code ISO 3166-1 alpha-2 country code
country_name Country name
registry Regional internet registry afrinic, lacnic, apnic, arin, ripe and more..
domain Website of Organization
num_ips_ipv4 Total number of IPv4 addresses announced by this AS
num_ips_ipv6 Total number of IPv6 addresses announced by this AS
as_name AS name
org_id Organization ID
comany_type Returns isp, business , hosting, other .
speed [Object] Returns an object containing Network Speed-related data.
speed->ping Returns the Network Speed ping of AS number.
speed->download Returns the Network Speed download of AS number.
speed->upload Returns the Network Speed upload of AS number.
peers [Object] Returns an object containing peers-related data.
peers->total_upstreams Returns the Total number of peers announced by this AS number
peers->list_upstreams Returns the list of AS announced by this AS number (e.g. AS1)
upstreams [Object] Returns an object containing upstreams-related data.
upstreams->total_upstreams Returns the Total number of upstreams announced by this AS number
upstreams->list_upstreams Returns the list of AS announced by this AS number (e.g. AS1)
downstreams [Object] Returns an object containing downstreams-related data.
downstreams->total_downstreams Returns the Total number of downstreams announced by this AS number
downstreams->list_downstreams Returns the list of AS announced by this AS number (e.g. AS1)
prefixes [Object] Returns an object containing prefixes-related data.
prefixes->total_prefixes Returns the Total number of prefixes announced by this AS
prefixes->list_prefixes Returns the list of prefixes CIDR announced by this AS (e.g. 41.96.0.0\/16)

Firewall

Do you want to block visitors by country or AS number ?

This API is currently only available as part of our enterprise

Examples

Here are sample command lines for fetching API service information :

HTTP Request

GET https://api.ipfinder.io/v1/firewall/{by}?token=$TOKEN&format=$Format

POST https://api.ipfinder.io/v1/firewall/{by}

# X-Authorization
 curl -H 'X-Authorization:  $TOKEN' -d "format=microtik"  -X POST http://api.ipfinder.io/v1/firewall/as2

# POST
 curl -d '{"token":"$TOKEN", "format": "microtik"}' -H "Content-Type: application/json" -X POST http://api.ipfinder.io/v1/firewall/as2

# GET 
 curl -X GET 'http://api.ipfinder.io/v1/firewall/as2?token=$TOKEN&format=apache_allow'
<?php
use ipfinder\ipfinder\IPfinder;
// Token
$client = new IPfinder('aac6070563e0d42ef5ca94fdc2b55fdd7546d7d6'); // YOUR_TOKEN_GOES_HERE
$asn = 'as1'; // as36947

// lookup Asn information or change to country code us , de, fr
$details = $client->getFirewall($asn,'nginx_deny');
var_dump($details);
import ipfinder

config = ipfinder.config('YOUR_TOKEN_GOES_HERE')

asn = 'as36947'

# lookup Firewall information

data = config.getFirewall(asn, 'nginx_deny')

data.details
const Ipfinder = require('ipfinder');
const ipfinder = new Ipfinder('YOUR_TOKEN_GOES_HERE');

ipfinder.getFirewall("AS1", 'nginx_deny').then(data => {
     console.log(data);
    // console.log(data.status_message);
}).catch(console.log);
require 'ipfinder'
config = Ipfinder::config('YOUR_TOKEN_GOES_HERE')

asn = 'as36947'
format = 'nginx_deny'
# lookup Asn Firewall information

firewall = config.getFirewall(asn, format)

puts firewall.inspect


  # shortopt
$ ipfinder -f AS1 --m juniper_junos
  # longopt
$ ipfinder --firewall AS1 --format juniper_junos

replace $Format with available Format name.

Parameter Default Description
token Required Your API key only for Enterprise key
by Required AS number as (e.g. AS1) or country ISO 3166-1 alpha-2 country code (e.g. US)
Format Required formats supported are apache_allow, apache_deny,nginx_allow,nginx_deny, CIDR, linux_iptables, netmask, inverse_netmask, web_config_allow, web_config_deny, cisco_acl, peer_guardian_2, network_object, cisco_bit_bucket, juniper_junos, microtik

Response details

The output formats supported are Nginx, Apache .htaccess, Linux iptables, CIDR, Netmask, Inverse Netmask, IIS web.config, Cisco ACL, PeerGuardian2, network-object, Cisco bit bucket, Juniper Junos and MicroTik. Please find the details below:

Response:

# -------------------------------------------------------
# Source: https://ipfinder.io/
# -------------------------------------------------------
# _____ ______   __  _             _
#|_   _|| ___ \ / _|(_)           | |
#  | |  | |_/ /| |_  _  _ __    __| |  ___  _ __
#  | |  |  __/ |  _|| || '_ \  / _` | / _ \| '__|
# _| |_ | |    | |  | || | | || (_| ||  __/| |
# \___/ \_|    |_|  |_||_| |_| \__,_| \___||_|
#
#______  _                             _  _
#|  ___|(_)                           | || |
#| |_    _  _ __  ___ __      __ __ _ | || |
#|  _|  | || '__|/ _ \ \ /\ / // _` || || |
#| |    | || |  |  __/ \ V  V /| (_| || || |
#\_|    |_||_|   \___|  \_/\_/  \__,_||_||_|
# -------------------------------------------------------
# [Important] Please update this list every month
# February 24, 2019, 8:24 pm
# Total ips: 74,240
# Download by ASN: AS2
# -------------------------------------------------------
add address=103.219.213.0/24 comment="AS2" list=IPfinder
add address=103.78.244.0/24 comment="AS2" list=IPfinder
add address=103.78.245.0/24 comment="AS2" list=IPfinder
add address=103.78.246.0/24 comment="AS2" list=IPfinder
add address=103.78.247.0/24 comment="AS2" list=IPfinder
add address=103.91.160.0/22 comment="AS2" list=IPfinder
add address=128.4.0.0/16 comment="AS2" list=IPfinder
add address=168.194.156.0/23 comment="AS2" list=IPfinder
add address=168.194.158.0/23 comment="AS2" list=IPfinder
add address=168.195.232.0/24 comment="AS2" list=IPfinder
add address=168.195.233.0/24 comment="AS2" list=IPfinder
add address=45.6.180.0/24 comment="AS2" list=IPfinder
add address=45.6.182.0/24 comment="AS2" list=IPfinder

....
....
....
....
....
....
Format Sample Output
Apache .htaccess allow allow from 8.8.8.0/24
Apache .htaccess deny deny from 8.8.8.0/24
Nginx allow allow 8.8.8.0/24;
Nginx deny deny 8.8.8.0/24;
CIDR 8.8.8.0/24
Linux iptables iptables -A INPUT -s 8.8.8.8/24 -j DROP
Netmask 8.8.8.0/255.255.255.0
Inverse Netmask 8.8.8.0 0.0.0.255
Web.config allow <ipSecurity allowUnlisted="false"><add ipAddress="8.8.8.0" subnetMask="255.255.255.0"/>
Web.config deny <ipSecurity allowUnlisted="true"><add ipAddress="8.8.8.0" subnetMask="255.255.255.0"/>
Cisco ACL deny ip 8.8.8.0 0.0.0.255 any
PeerGuardian2 HOST:8.8.8.0-8.255.255.255
network-object network-object 8.8.8.0 255.255.255.0
Cisco bit bucket ip route 8.8.8.0 255.255.255.0 Null0
Juniper Junos set 8.8.8.0/24
MicroTik add address=8.8.8.0/24 comment="Danger" list=MyList

Get service status

Examples

Here are sample command lines for fetching API service information :

HTTP Request

GET https://api.ipfinder.io/v1/info

POST https://api.ipfinder.io/v1/info

The parameters are defined as follows :

# With token query parameter

$ curl -X GET https://api.ipfinder.io/v1/info?token=$TOKEN

# With Basic Auth
$ curl -u $TOKEN:  https://api.ipfinder.io/v1/info

# With X-Authorization token
$ curl -H 'X-Authorization: $TOKEN' https://api.ipfinder.io/v1/info
<?php
use ipfinder\ipfinder\IPfinder;

// Token
$client = new IPfinder('YOUR_TOKEN_GOES_HERE');


// lookup token information

$details = $client->getStatus();

var_dump($details);

// get and print Number of IP address queries left for the day
echo $details->queriesLeft."\n";
import ipfinder

config = ipfinder.config('YOUR_TOKEN_GOES_HERE')

# lookup TOKEN information
data = config.getStatus()


data.details
const Ipfinder = require('ipfinder');
const ipfinder = new Ipfinder('YOUR_TOKEN_GOES_HERE');

ipfinder.getStatus().then(data => {
     console.log(data);
    // console.log(data.status_message);
}).catch(console.log);
require 'ipfinder'
config = Ipfinder::config('YOUR_TOKEN_GOES_HERE')

# lookup IP TOKEN information
data = config.getStatus()

puts data.inspect


  # shortopt
$ ipfinder -s
  # longopt
$ ipfinder --status

Parameter Default Description
token Required Your API key or the string "free" for the free API

Response Objects details

Full Response

{
    "apiKey": "$TOKEN",
    "queriesPerDay": 50000,
    "queriesLeft": 49993,
    "asqueriesPerDay": 1000,
    "asqueriesLeft": 976,
    "key_type": "E50",
    "key_info": "Enterprise API 50.000 queries per day",
    "status": "active"
}

Response Object Description
apiKey Your API key
queriesPerDay Quota of daily IP address queries
queriesLeft Number of IP address queries left for the day
asqueriesPerDay Quota of daily AS number queries only for Pro and Enterprise KEY
asqueriesLeft Number of AS number queries left for the day only for Pro and Enterprise KEY
key_type API key info
key_info API key description
status The status of your API service active canceled

IP Address Ranges

Our IP address ranges API will return a list of all of the IP addresses ranges assigned to or operated by a company, identified by the Organization name. So, you provide a Organization name, and we return all of the IP address ranges in CIDR format that belong to that company.

This API is currently only available as part of our enterprise

Examples

Here are sample command lines for fetching API service information :

HTTP Request

GET https://api.ipfinder.io/v1/ranges/$ORGNAME?token=$token

POST https://api.ipfinder.io/v1/ranges/$ORGNAME

The parameters are defined as follows :

# With POST
curl -X POST -d '{"token":"$TOKEN"}' -H "Content-Type: application/json" http://api.sample.com/v1/ranges/$ORGNAME

# With token query parameter

CURL -X GET 'http://api.sample.com/v1/ranges/Telecom%20Algeria?token=$TOKEN'

<?php
use ipfinder\ipfinder\IPfinder;

// Token
$client = new IPfinder('YOUR_TOKEN_GOES_HERE');

// Organization name
$org = 'Telecom Algeria';

// lookup Organization information
$details = $client->getRanges($org);

var_dump($client);

// print Organization name url encode
echo $client->urlencode;

import ipfinder

config = ipfinder.config('YOUR_TOKEN_GOES_HERE')

# Organization name
org = 'Telecom Algeria'

# lookup Organization information
data = config.getRanges(org)

data.details
const Ipfinder = require('ipfinder');
const ipfinder = new Ipfinder('YOUR_TOKEN_GOES_HERE');

ipfinder.getRanges("Telecom Algeria").then(data => {
     console.log(data);
    // console.log(data.status_message);
}).catch(console.log);
require 'ipfinder'
config = Ipfinder::config('YOUR_TOKEN_GOES_HERE')

# Organization name
org = 'Telecom Algeria'

# lookup Organization information
range = config.getRanges(org)

puts range.inspect


  # shortopt
$ ipfinder -r  'Telecom Algeria'
  # longopt
$ ipfinder --ranges  'Telecom Algeria'

Make sure to convert $ORGNAME into URL encoding

Parameter Default Description
token Required Your API key
ORGNAME Required Organization name convert into URL encoding URL encoding

Response Objects details

{
    "status": "ok",
    "status_message": "Query was successful",
    "org_name": "University of Indianapolis",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_name": "United States",
    "domain": "unive.nl",
    "num_ranges": "724",
    "num_ipv4": "13,120,004",
    "num_ipv6": "11,648,129,627,049,650,863,615,699,320,832",
    "num_asn": 89,
    "list_asn": [
        {
            "asn": "396892",
            "OrgId": "UNIVER-246",
            "Total_prefix": "4",
            "Total_v4": "2,560",
            "Total_v6": "0"
        },
        {
            "asn": "394003",
            "OrgId": "UMD",
            "Total_prefix": "1",
            "Total_v4": "65,536",
            "Total_v6": "0"
        },
        {
            "asn": "328215",
            "OrgId": "ORG-UCS1-AFRINIC",
            "Total_prefix": "1",
            "Total_v4": "256",
            "Total_v6": "0"
        }
        ....
        ....
        ....
        ....
    ],
    "list_prefixes": [

        {
            "asn": "2",
            "prefix": "103.219.213.0\/24"
        },
        {
            "asn": "2",
            "prefix": "128.4.0.0\/16"
        },
        {
            "asn": "2",
            "prefix": "168.194.156.0\/23"
        },
        {
            "asn": "2",
            "prefix": "168.194.158.0\/23"
        },
        {
            "asn": "2",
            "prefix": "168.195.232.0\/24"
        },
        {
            "asn": "2",
            "prefix": "168.195.233.0\/24"
        }
        ....
        ....
        ....
        ....
    ]
}

Response Object Description
domain Returns provided domain name
num_ranges Returns total number of CIDR
num_ipv4 Returns Total number of IPV4
num_ipv6 Returns total number of IPV6
num_asn Returns total number of AS number
ranges [Object] Returns an object containing CIDR-related data.

Domain

This API is currently only available as part of our enterprise

Get Domain IP

Here are sample command lines for fetching :

# With token query parameter

curl -XGET https://api.ipfinder.io/v1/domain/google.com?token=$TOKEN

<?php
use ipfinder\ipfinder\IPfinder;

// Token
$client = new IPfinder('YOUR_TOKEN_GOES_HERE');

// domain name
$name = 'google.com';

// lookup Organization information
$details = $client->getDomain($name);

var_dump($details);


import ipfinder

config = ipfinder.config('YOUR_TOKEN_GOES_HERE')


#  domain name
name = 'google.com';

data = config.getDomain(name)

data.details
const Ipfinder = require('ipfinder');
const ipfinder = new Ipfinder('YOUR_TOKEN_GOES_HERE');

ipfinder.getDomain("google.com").then(data => {
     console.log(data);
    // console.log(data.status_message);
}).catch(console.log);
require 'ipfinder'
config = Ipfinder::config('YOUR_TOKEN_GOES_HERE')

# lookup domain name data
name = 'google.com'

domain = config.getDomain(name)

puts domain.inspect


  # shortopt
$ ipfinder -d google.dz
  # longopt
$ ipfinder --domain facebook.com

HTTP Request

GET https://api.ipfinder.io/v1/domain/$DomainName?token=$TOKEN&format=$Format

POST https://api.ipfinder.io/v1/domain/$DomainName

The parameters are defined as follows :

Parameter Default Description
token Required Your API key
$DomainName Required The API supports passing in a single website name domain name
format optional available format json jsonp php xml

Domain IP Objects details

{
    "status": "ok",
    "status_message": "Query was successful",
    "ip": "172.217.171.238",
    "domain": "google.com",
    "domain_status": true,
    "continent_code": "AS",
    "continent_name": "Asia",
    "country_code": "SG",
    "country_name": "Singapore",
    "country_native_name": "Singapore",
    "region_name": "Central Singapore",
    "city": "Singapore",
    "latitude": "1.28009",
    "longitude": "103.851",
    "asn": "AS15169",
    "organization": "Google LLC"
}
Response Object Description
ip IP address
domain Requested domain
domain_status If domain is live Return true else false domain is down
continent_code 2-letter continent code
continent_name Continent name
country_code ISO 3166-1 alpha-2 country code
country_native_name Country native name
region_name State or province name
city City name
latitude Decimal latitude
longitude Decimal longitude
asn the Autonomous System Number associated with the IP
organization the name of the organization associated with the IP

Get Domain IP history

Here are sample command lines for fetching API service information :

# With token query parameter

curl -XGET https://api.ipfinder.io/v1/domainhistory/google.com?token=$TOKEN

<?php
use ipfinder\ipfinder\IPfinder;

// Token
$client = new IPfinder('YOUR_TOKEN_GOES_HERE');

// domain name
$name = 'google.com';

// lookup Organization information
$details = $client->getDomainHistory($name);

var_dump($details);


import ipfinder

config = ipfinder.config('YOUR_TOKEN_GOES_HERE')

# domain name
name = 'google.com';

data = config.getDomainHistory(name)

data.details
const Ipfinder = require('ipfinder');
const ipfinder = new Ipfinder('YOUR_TOKEN_GOES_HERE');

ipfinder.getDomainHistory("google.com").then(data => {
     console.log(data);
    // console.log(data.status_message);
}).catch(console.log);
require 'ipfinder'
config = Ipfinder::config('YOUR_TOKEN_GOES_HERE')

# lookup domain name IP history
name = 'google.com'

data = config.getDomainHistory(name)

puts data.inspect


  # shortopt
$ ipfinder -dh google.com
  # longopt
$ ipfinder --dhistory google.com

HTTP Request

GET https://api.ipfinder.io/v1/domainhistory/$DomainName?token=$TOKEN&format=$Format

POST https://api.ipfinder.io/v1/domainhistory/$DomainName

The parameters are defined as follows :

Parameter Default Description
token Required Your API key
$DomainName Required The API supports passing in a single website name domain name
format optional available format json jsonp php xml

Domain IP history Objects details

{
    "status": "ok",
    "status_message": "Query was successful",
    "total_domain": 5,
    "list_domain": [
        [
            {
                "domain_name": "google.com",
                "address": "172.217.171.238",
                "country": "SG",
                "asn": "15169",
                "organization": "Google LLC",
                "last_seen_on": "2019-06-16 13:47:09"
            },
            {
                "domain_name": "google.com",
                "address": "216.58.198.78",
                "country": "IT",
                "asn": "15169",
                "organization": "Google LLC",
                "last_seen_on": "2019-06-16 13:43:30"
            },
            {
                "domain_name": "google.com",
                "address": "172.217.168.206",
                "country": "SG",
                "asn": "15169",
                "organization": "Google LLC",
                "last_seen_on": "2019-06-15 18:29:24"
            },
            {
                "domain_name": "google.com",
                "address": "172.217.17.110",
                "country": "US",
                "asn": "15169",
                "organization": "Google LLC",
                "last_seen_on": "2019-06-15 18:29:20"
            },
            {
                "domain_name": "google.com",
                "address": "172.217.17.46",
                "country": "US",
                "asn": "15169",
                "organization": "Google LLC",
                "last_seen_on": "2019-06-07 10:02:15"
            }
        ]
    ]
}
Response Object Description
total_domain Returns the
list_domain [Object] Returns an object containing list domain name
list_domain->domain_name Returns the domain name
list_domain->address Returns IP address
list_domain->country Returns ISO 3166-1 alpha-2 country code
list_domain->asn Returns the Autonomous System Number associated with the IP.
list_domain->last_seen_on Returns the last seen date

Get list Domain By ASN, Country,Ranges

Here are sample command lines for fetching API service information :

# Get list domain by as11
curl -XGET https://api.ipfinder.io/v1/domainby/AS11?token=$TOKEN

# Get list domain by country  DZ
curl -XGET https://api.ipfinder.io/v1/domainby/DZ?token=$TOKEN

# Get list domain by organization name
curl -XGET https://api.ipfinder.io/v1/domainby/Google%20LLC?token=$TOKEN


<?php
use ipfinder\ipfinder\IPfinder;

// Token
$client = new IPfinder('YOUR_TOKEN_GOES_HERE');

// domain name
$by = 'Google LLC';

// lookup Organization information
$details = $client->getDomainBy($name);

var_dump($details);


import ipfinder

config = ipfinder.config('YOUR_TOKEN_GOES_HERE')

# list live domain by country DZ,US,TN,FR,MA
by = 'DZ';

dby = config.getDomainBy(by)

dby.details

const Ipfinder = require('ipfinder');
const ipfinder = new Ipfinder('YOUR_TOKEN_GOES_HERE');

ipfinder.getDomainBy("DZ").then(data => {
     console.log(data);
    // console.log(data.status_message);
}).catch(console.log);
require 'ipfinder'
config = Ipfinder::config('YOUR_TOKEN_GOES_HERE')

# lookup  live list domain by country DZ,US,TN,FR,MA
by = 'DZ'

dby = config.getDomainBy(by)

puts dby.inspect


  # shortopt
$ ipfinder -dl DZ
  # longopt
$ ipfinder --dlist "Google LLC"

HTTP Request

GET https://api.ipfinder.io/v1/domainby/{$select_by}?token=$TOKEN&format=$format

POST https://api.ipfinder.io/v1/domainby/{$select_by}

The parameters are defined as follows :

Parameter Default Description
token Required Your API key
$select_by Required The API supports passing in a single website name domain name
format optional available format json jsonp php xml

Domain By ASN Objects details

{
    "status": "ok",
    "status_message": "Query was successful",
    "select_by": "country US",
    "total_domain": ???,
    "list_domain": [
        [
            {
                "domain_name": "google.com",
                "address": "172.217.17.46",
                "country": "US",
                "asn": "15169",
                "organization": "Google LLC"
            },
            {
                "domain_name": "sa3i9a.com",
                "address": "104.24.97.206",
                "country": "US",
                "asn": "13335",
                "organization": "  NOC"
            },
            {
                "domain_name": "stackoverflow.com",
                "address": "151.101.1.69",
                "country": "US",
                "asn": "54113",
                "organization": "Fastly"
            },
            {
                "domain_name": "stackoverflow.com",
                "address": "151.101.193.69",
                "country": "US",
                "asn": "54113",
                "organization": "Fastly"
            },
            {
                "domain_name": "google.com",
                "address": "172.217.17.110",
                "country": "US",
                "asn": "15169",
                "organization": "Google LLC"
            }
            ....
            ....
            ....
            ....
            ....
            ....
        ]
    ]
}
Response Object Description
select_by Returns Requested $select_by ASN,Country,Ranges
total_domain Returns number of domain
list_domain [Object] Returns an object containing list domain name
list_domain->domain_name Returns the domain name
list_domain->address Returns IP address
list_domain->country Returns ISO 3166-1 alpha-2 country code
list_domain->asn Returns the Autonomous System Number associated with the IP.
list_domain->organization Returns the name of the organization associated with the IP.

Libraries

Language Libraries

Official libraries for common programming languages, like PHP, Python etc.

Language Status Link Package Manager
Javascript Released ipfinder-io/ip-finder-node ipfinder
Java In progress
Python Released ipfinder-io/ip-finder-python ipfinder-io
C# In progress
PHP Released ipfinder-io/ip-finder-php ipfinder/ipfinder
Ruby Released ipfinder-io/ip-finder-ruby Ipfinder
Go In progress
R In progress
Perl In progress

Framework Libraries

Official libraries for common frameworks. These libraries should use the official lanaguge library as a dependency, so for example the Django library should use the Python library.

In the framework libraries we can assume more about the developer's use case, and we probably have access to more information, such as a HTTP request object. We can therefore implement additional functionality that doesn't make sense in the core language library. This includes bot filtering (not sending requests to our API if the user agent belongs to a "bot").

The framework libraries should make it as simple as possible to use our API. For example, ideally only a few lines of code would be required to get ipfinder data for everyone accessing your Ruby site.

Framework Status Link
Express (NodeJS - Javascript) In progress
Spring (Java) In progress
Laravel (PHP) In progress
CodeIgniter (PHP) Released ipfinder-io/codeigniter-ipfinder
Django (Python) In progress
Rails (Ruby) In progress

Third party libraries

There are a large number of unofficial ipfinder libraries written by third parties. While these aren't maintained by us and haven't been tested by us these libraries can be a great way to get started quickly with ipfinder if you're using a language or framework that we don't have an official library for. Search GitHub for ipfinder libraries.

Changelog

All notable changes to this API will be documented in this file.

August, 2019

July, 2019

June, 2019

May, 2019

March, 2019

Errors

Whenever a requested resource is not available or an API call fails for another reason, a JSON error is returned. Errors always come with an error code and a description.

Server

Server error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The requested is hidden for administrators only.
404 Not Found -- The specified could not be found.
405 Method Not Allowed -- invalid method.
406 Not Acceptable -- You requested a format Not Acceptable .
429 Too Many Requests -- You're requesting too many ! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

API

API error codes:

Error Code Error id Meaning
104 usage_limit_reached You have reached your usage limit. Upgrade your plan if necessary.
404 invalid_access_key No API Key was specified or an invalid API Key was specified.
404 missing_token_key No API Key was specified.
402 expired_paymant expired paymant please Upgrade your plan
402 non_paymant non paymant Please Login to your dashbord and make order
105 function_access_restricted asn api note include in basic or Free acoount please Upgrade your plan
405 method_not_allowed Method Not Allowed
404 404_not_found The requested resource does not exist.