NAV Navbar
cURL PHP Python Node.js Ruby JAVA Lua dlang Rlang elixir Swift Go Dart 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

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE", ""); 

        try {
            // lookup your IP address information
            IPResponse response = ipfinder.authentication();

            System.out.println(response.toString());

            // print city name
            System.out.println(response.getCity());

        } catch (IPfinderException e) {
            // Handle error
        }

local inspect = require('inspect')
local ipfinder = require('ipfinder')

accconf Ipfinder:init("YOUR_TOKEN_GOES_HERE")

-- lookup your IP address information
auth = conf:Authentication()

print(inspect(auth))

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE");

        try {
            // lookup your IP address information
            JSONValue response = ipfinder.authentication();

            writeln(response);

            // print city name
            writeln(response.getCity());

        } catch (Exception e) {
            // Handle error
        }

require(ipfinder)

accconf Ipfinder(token="YOUR_TOKEN_GOES_HERE")

# lookup your IP address information
auth <- Authentication(conf)

auth
# print your ip
auth$ip

iex> conf = Ipfinder.new("YOUR_TOKEN_GOES_HERE")

# lookup your IP address information
iex> {:ok, auth} = Ipfinder.Authentication(conf)

iex> auth
# print your ip
iex> auth.ip

import ipfinder

let ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE")

// lookup your IP address information
let auth = ipfinder.Authentication()

print(auth)

// lookup your IP address information
func main() {
  conf := ipfinder.New("YOUR_TOKEN_GOES_HERE", "")
  auth, err := conf.Authentication()

  if err != nil {
    fmt.Println("Error : ", err)
  } else {
    fmt.Println(auth)
  }
}

import 'package:ipfinder/ipfinder.dart';

void main() async {
  Ipfinder ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE");
  IpResponse auth = await ipfinder.authentication();
  print(auth.toJson()); // print json data
  print(auth.location); // print location
}


  # 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.

HTTPS / SSL

Our API is available over a secure HTTPS connection for all users, even on the free plan. Simply add https:// to the request URLs to make the requests secure.

# Get details for your own IP address over HTTPS
$ curl https://api.ipfinder.io/v1/?token=$TOKEN

Rate Limits

Free usage of our API is limited to 120,000 API requests per month or 4000 API requests per day . If you exceed that limit we'll return a 104 HTTP status code to you.

Paid plans come with higher monthly limits, and configurable alerts.

Filtering Responses

You can filter the API response down to specific fields or objects by adding the field or object name to the URL. In the case of a field you'll get it returned in plaintext, and an object will get returned as JSON.

# Get json the type field as plaintext
$ curl -X GET https://api.ipfinder.io/v1/1.0.0.0?token=free
{
    "status": "ok",
    "status_message": "Query was successful",
    "ip": "1.0.0.0",
    "type": "IPV4",
    "continent_code": "OC",
    "continent_name": "Oceania",
    "country_code": "AU",
    "country_name": "Australia",
    "country_native_name": "Australia",
    "region_name": "Queensland",
    "city": "South Brisbane"
}
$ curl -XGET 'https://api.ipfinder.io/v1/1.0.0.0?token=free&propertyName=continent_code'
"OC"
$ curl -XGET 'https://api.ipfinder.io/v1/1.0.0.0?token=free&propertyName=type'
"IPV4"
$ curl -XGET 'https://api.ipfinder.io/v1/1.0.0.0?token=free&propertyName=city'
"South Brisbane"

JSONP/CORS Requests

JSONP and CORS are supported, allowing you to use ipfinder.io entirely in client-side code. For JSONP you just need to specify the callback parameter, e.g. https://api.ipfinder.io/v1/1.0.0.0?token=free&format=jsonp&callback=callback. Most javascript libraries will automatically handle this for you though.

Here's a jQuery example that logs the client IP and country:

$.get("https://api.ipfinder.io/v1/1.0.0.0?token=free", function(response) {
  console.log(response.ip, response.country_code);
}, "jsonp")

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 IP

# 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

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE", ""); 

        try {

            // lookup your IP address information
            String ip = "5.2.0.2";

            IPResponse response = ipfinder.getAddressInfo(ip);

            System.out.println(response.toString());

            // print city name
            System.out.println(response.getCity());

        } catch (IPfinderException e) {
            // Handle error
        }

local inspect = require('inspect')
local ipfinder = require('ipfinder')

conf = Ipfinder:init("YOUR_TOKEN_GOES_HERE")

-- GET Get details for 1.0.0.0
ip = conf:getAddressInfo("1.0.0.0")

print(inspect(ip))

print(ip.ip)

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE");

        try {

            // lookup your IP address information
            string ip = "5.2.0.2";

            JSONValue response = ipfinder.getAddressInfo(ip);

            writeln(response);

            // print city name
            writeln(response.getCity());

        } catch (Exception e) {
            // Handle error
        }

require(ipfinder)

conf <- Ipfinder(token="YOUR_TOKEN_GOES_HERE")

# GET Get details for 1.0.0.0
ip <- getAddressInfo(conf,"1.0.0.0")
# print data
ip

iex> conf = Ipfinder.new("YOUR_TOKEN_GOES_HERE")

# GET Get details for 1.0.0.0
iex> {:ok, ip} = Ipfinder.getAddressInfo(conf,"1.0.0.0")
# print data
ip

import ipfinder
let ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE")

// lookup IP address information
let ip = ipfinder.getAddressInfo("1.0.0.0")

print(ip)

// lookup IP address information
func main() {
  conf := ipfinder.New("YOUR_TOKEN_GOES_HERE", "")
  ip, err := conf.GetAddressInfo("1.0.0.0")

  if err != nil {
    fmt.Println("Error : ", err)
  } else {
    fmt.Println(ip)
  }
}

import 'package:ipfinder/ipfinder.dart';

void main() async {
  Ipfinder ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE");
  IpResponse ip = await ipfinder.getAddressInfo("1.0.0.0");
  print(ip.toJson()); // print json data
}


  # 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:\/\/ipfinder.io\/flag\/usa.svg",
        "flag_png": "http:\/\/ipfinder.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

The AS API lets you request details about an AS number, it is included with PROFESSIONAL and Enterprise API plans.

Examples AS

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

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE", ""); 

        try {
            // lookup Asn information
            String asn = "as36947";

            AsnResponse response = ipfinder.getAsn(asn);

            // print data
            System.out.println(response);

            // print continent name
            System.out.println(response.getContinentName());
        } catch (IPfinderException e) {
            // Handle error
        }

local inspect = require('inspect')
local ipfinder = require('ipfinder')

conf = Ipfinder:init("YOUR_TOKEN_GOES_HERE")

asn = conf:getAsn("AS1")

print(inspect(asn))

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE");

        try {
            // lookup Asn information
            string asn = "as36947";

            JSONValue response = ipfinder.getAsn(asn);

            // print data
            writeln(response);

        } catch (Exception e) {
            // Handle error
        }

require(ipfinder)

conf <- Ipfinder(token="YOUR_TOKEN_GOES_HERE")

asn <- getAsn(conf,"AS1")
# print data
asn

iex> conf = Ipfinder.new("YOUR_TOKEN_GOES_HERE")

iex> {:ok, asn} = Ipfinder.getAsn(conf,"AS1")
# print data
iex> asn

import ipfinder
let ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE")

// lookup Asn information
let asn = ipfinder.getAddressInfo("as1")

print(asn)

// lookup Asn information
func main() {
  conf := ipfinder.New("YOUR_TOKEN_GOES_HERE", "") 
  asn, err := conf.GetAsn("as1")

  if err != nil {
    fmt.Println("Error : ", err)
  } else {
    fmt.Println(asn)
  }
}

import 'package:ipfinder/ipfinder.dart';

void main() async {
  Ipfinder ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE");
  AsnResponse asn = await ipfinder.getAsn("as1");
  print(asn.toJson()); // print json data
}


  # 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 Firewall

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('YOUR_TOKEN_GOES_HERE'); // 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

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE", "");

        try {

            String asn = "as36947";

            String format = "nginx_deny";

            String response = ipfinder.getFirewall(asn,format);

            // print data
            System.out.println(response);

        } catch (IPfinderException ex) {
            // Handle error
            System.out.println(e);
        }

local inspect = require('inspect')
local ipfinder = require('ipfinder')

conf = Ipfinder:init("YOUR_TOKEN_GOES_HERE")

-- lookup Asn Firewall information
fire = conf:getFirewall("AS1", 'nginx_deny')

print(inspect(fire))

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE");

        try {

            string asn = "as36947";

            string format = "nginx_deny";

            string response = ipfinder.getFirewall(asn,format);

            // print data
            writeln(response);

        } catch (Exception ex) {
            // Handle error
            writeln(e);
        }

require(ipfinder)

conf <- Ipfinder(token="YOUR_TOKEN_GOES_HERE")

# lookup Asn Firewall information
fire <- getFirewall(conf,"AS1", 'nginx_deny')

fire

iex> conf = Ipfinder.new("YOUR_TOKEN_GOES_HERE")

# lookup Asn Firewall information
iex> {:ok, fire} = Ipfinder.getFirewall(conf,"AS1", 'nginx_deny')

iex>fire

import ipfinder
let ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE")

// lookup Asn Firewall information
let fire = ipfinder.getFirewall("AS1", format:"nginx_deny")

print(fire)

// lookup Asn Firewall information
func main() {
  conf := ipfinder.New("YOUR_TOKEN_GOES_HERE", "") 
  fire, err := conf.GetFirewall("as1", "nginx_deny")

  if err != nil {
    fmt.Println("Error : ", err)
  } else {
    fmt.Println(fire)
  }
}

import 'package:ipfinder/ipfinder.dart';

void main() async {
  Ipfinder ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE");
  Response fire = await ipfinder.getFirewall("AS1", "nginx_deny");
  print(fire); // print json data
}


  # 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 status

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

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE", "");

        try {

            StatusResponse response = ipfinder.getStatus();

            // print data
            System.out.println(response);
        } catch (IPfinderException ex) {
            // Handle error
            System.out.println(e);
        }

local inspect = require('inspect')
local ipfinder = require('ipfinder')

conf = Ipfinder:init("YOUR_TOKEN_GOES_HERE")

-- lookup IP TOKEN information
status = conf:getStatus()

print(inspect(status))

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE");

        try {

            JSONValue response = ipfinder.getStatus();

            // print data
            writeln(response);
        } catch (Exception ex) {
            // Handle error
            writeln(e);
        }

require(ipfinder)

conf <- Ipfinder(token="YOUR_TOKEN_GOES_HERE")

# lookup IP TOKEN information
status <- getStatus(conf)

status

iex> conf = Ipfinder.new("YOUR_TOKEN_GOES_HERE")

# lookup IP TOKEN information
iex> {:ok, status} = Ipfinder.getStatus(conf)

iex> status

import ipfinder
let ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE")

// lookup IP TOKEN information
let status = ipfinder.getStatus()

print(status)

// lookup IP TOKEN information
func main() {
  conf := ipfinder.New("YOUR_TOKEN_GOES_HERE", "")
  stats, err := conf.GetStatus()

  if err != nil {
    fmt.Println("Error : ", err)
  } else {
    fmt.Println(stats)
  }
}

import 'package:ipfinder/ipfinder.dart';

void main() async {
  Ipfinder ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE");
  StatusResponse status = await ipfinder.getStatus();
  print(status.toJson()); // print json data
}


  # 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 Ranges

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.ipfinder.io/v1/ranges/$ORGNAME

# With token query parameter

CURL -X GET 'http://api.ipfinder.io/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

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE", "");

        try {

            String org = "Telecom Algeria";

            RangeResponse response = ipfinder.getRanges(org);

            // print data
            System.out.println(response);

        } catch (IPfinderException ex) {
            // Handle error
            System.out.println(e);
        }

local inspect = require('inspect')
local ipfinder = require('ipfinder')

conf = Ipfinder:init("YOUR_TOKEN_GOES_HERE")

-- lookup Organization information
range = conf:getRanges("Telecom Algeria")

print(inspect(range))

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE");

        try {

            string org = "Telecom Algeria";

            JSONValue response = ipfinder.getRanges(org);

            // print data
            writeln(response);

        } catch (Exception ex) {
            // Handle error
            writeln(e);
        }

require(ipfinder)

conf <- Ipfinder(token="YOUR_TOKEN_GOES_HERE")

# lookup Organization information
range <- getRanges(conf,"Telecom Algeria")

range

iex> conf = Ipfinder.new("YOUR_TOKEN_GOES_HERE")

# lookup Organization information
iex> {:ok, range} = Ipfinder.getRanges(conf,"Telecom Algeria")

iex> range

import ipfinder
let ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE")

// lookup Organization information
let range = ipfinder.getRanges("Telecom Algeria")

print(range)

// lookup Organization information
func main() {
  conf := ipfinder.New("YOUR_TOKEN_GOES_HERE", "")
  ranges, err := conf.GetRanges("Telecom Algeria")

  if err != nil {
    fmt.Println("Error : ", err)
  } else {
    fmt.Println(ranges)
  }
}

import 'package:ipfinder/ipfinder.dart';

void main() async {
  Ipfinder ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE");
  RangeResponse range = await ipfinder.getRanges("Telecom Algeria");
  print(range.toJson()); // print json data
}


  # 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

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE", "");

        try {

            String name = "google.com";

            DomainResponse response = ipfinder.getDomain(name);

            // print data
            System.out.println(response);

        } catch (IPfinderException ex) {
            // Handle error
            System.out.println(e);
        }

local inspect = require('inspect')
local ipfinder = require('ipfinder')

conf = Ipfinder:init("YOUR_TOKEN_GOES_HERE")

domain = conf:getDomain("google.fr")

print(inspect(domain))

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE");

        try {

            string name = "google.com";

            JSONValue response = ipfinder.getDomain(name);

            // print data
            writeln(response);

        } catch (Exception ex) {
            // Handle error
            writeln(e);
        }

require(ipfinder)

conf <- Ipfinder(token="YOUR_TOKEN_GOES_HERE")

domain <- getDomain(conf,"google.fr")

domain

iex> conf = Ipfinder.new("YOUR_TOKEN_GOES_HERE")

iex> {:ok, domain} = Ipfinder.getDomain(conf,"google.fr")

iex> domain

import ipfinder
let ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE")
// domain name
let domain = ipfinder.getDomain("google.ma")

print(domain)

// Get domain name
func main() {
  conf := ipfinder.New("YOUR_TOKEN_GOES_HERE", "")
  domain, err := conf.GetDomain("google.dz")

  if err != nil {
    fmt.Println("Error : ", err)
  } else {
    fmt.Println(domain)
  }
}

import 'package:ipfinder/ipfinder.dart';

void main() async {
  Ipfinder ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE");
  DomainResponse domain = await ipfinder.getDomain("google.com");
  print(domain.toJson()); // print json data
}


  # 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

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE", "");

        try {
            String by = "DZ";

            DomainByResponse response = ipfinder.getDomainBy(by);

            // print data
            System.out.println(response);

        } catch (IPfinderException ex) {
            // Handle error
            System.out.println(e);
        }
    }

local inspect = require('inspect')
local ipfinder = require('ipfinder')

conf = Ipfinder:init("YOUR_TOKEN_GOES_HERE")
-- domain name IP history
domain = conf:getDomainHistory("google.fr")

print(inspect(domain))

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE");

        try {

            string name = "google.com";

            JSONValue response = ipfinder.getDomainHistory(name);

            // print data
            writeln(response);

        } catch (Exception ex) {
            // Handle error
            writeln(e);
        }

require(ipfinder)

conf <- Ipfinder(token="YOUR_TOKEN_GOES_HERE")
# domain name IP history
domain <- getDomainHistory(conf,"google.fr")

domain

iex> conf = Ipfinder.new("YOUR_TOKEN_GOES_HERE")

# domain name IP history
iex> {:ok, domain} = Ipfinder.getDomainHistory(conf,"google.fr")

iex> domain

import ipfinder
let ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE")
// domain name IP history
let domain = ipfinder.getDomainHistory("google.in")

print(domain)

// Get domain name IP list history
func main() {
  conf := ipfinder.New("YOUR_TOKEN_GOES_HERE", "") 
  domain, err := conf.GetDomainHistory("google.dz")

  if err != nil {
    fmt.Println("Error : ", err)
  } else {
    fmt.Println(domain)
  }
}

import 'package:ipfinder/ipfinder.dart';

void main() async {
  Ipfinder ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE");
  DomainHtResponse domain = await ipfinder.getDomainHistory("google.com");
  print(domain.toJson()); // print json data
}


  # 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

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE", "");

        try {

            String name = "google.com";

            DomainHtResponse response = ipfinder.getDomainHistory(name);

            // print data
            System.out.println(response);

        } catch (IPfinderException ex) {
            // Handle error
            System.out.println(e);
        }

local inspect = require('inspect')
local ipfinder = require('ipfinder')

conf = Ipfinder:init("YOUR_TOKEN_GOES_HERE")
-- list live domain by country DZ,US,TN,FR,MA

domain = conf:getDomainBy("FR")

print(inspect(domain))

        Ipfinder ipfinder = new Ipfinder("YOUR_TOKEN_GOES_HERE");

        try {
            string by = "DZ";

            JSONValue response = ipfinder.getDomainBy(by);

            // print data
            writeln(response);

        } catch (Exception ex) {
            // Handle error
            writeln(e);
        }

require(ipfinder)

conf <- Ipfinder(token="YOUR_TOKEN_GOES_HERE")
# list live domain by country DZ,US,TN,FR,MA

by <- getDomainBy(conf,"FR")

by

iex> conf = Ipfinder.new("YOUR_TOKEN_GOES_HERE")

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

iex> {:ok, by} = Ipfinder.getDomainBy(conf,"FR")

iex> by

import ipfinder
let ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE")
// list live domain by country DZ,US,TN,FR,MA
let by = ipfinder.getDomainBy("DZ")

print(by)

// list live domain by country DZ,US,TN,FR,MA
func main() {
  conf := ipfinder.New("YOUR_TOKEN_GOES_HERE", "") 
  domain, err := conf.GetDomainBy("DZ")

  if err != nil {
    fmt.Println("Error : ", err)
  } else {
    fmt.Println(domain)
  }
}

import 'package:ipfinder/ipfinder.dart';

void main() async {
  Ipfinder ipfinder = Ipfinder("YOUR_TOKEN_GOES_HERE");
  DomainByResponse by = await ipfinder.getDomainBy("DZ");
  print(by.toJson()); // print json data
}


  # 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.

IPFinder CLI (Command Line Interface)

Installation

Via composer

First, download the IPfinder cli using Composer: composer global require ipfinder-io/ip-finder-cli

Linux Distributions / macOS

## using curl

$ curl -LO https://github.com/ipfinder-io/ip-finder-cli/releases/download/v1.0.2/ipfinder.phar
## using wget
$ wget https://github.com/ipfinder-io/ip-finder-cli/releases/download/v1.0.2/ipfinder.phar
$ chmod +x ipfinder.phar
$ sudo mv ipfinder.phar /usr/bin/ipfinder
$ ipfinder -h

Windows

  1. Download IPFINDER PHAR from github
  2. Create a directory for PHP binaries; e.g., C:\bin
  3. Open a command line (e.g., press Windows+R » type cmd » ENTER)
  4. Create a wrapping batch script (results in C:\bin\ipfinder.cmd):
C:\Users\username> cd C:\bin
C:\bin> echo @php "%~dp0ipfinder.phar" %* > ipfinder.cmd
C:\bin> exit
  1. Open a new command line and confirm that you can execute IPfinder from any path: C:\Users\username> ipfinder --help `

Command list

shortopts longopts Description
-h --help This help text
-o --output save to a given file
-u --update App Code update
-a --auth lookup your IP address information.
-m --format fetching IP address information.
-i --ip firewall supported format https://ipfinder.io/docs/?shell#firewall.
-n --asn fetching AS number information.
-r --ranges fetching IP Address Ranges information.
-f --firewall fetching firewall information
-d --domain Get information for Domain IP.
-d --dhistory Get information for Domain IP history.
-dl --dlist Get information for list Domain By ASN, Country,Ranges.
-s --status Get information for your token.
-c --config Add your Token and lang
-l --shell Run interactively

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 Released ipfinder-io/ip-finder-java ipfinder-io
Python Released ipfinder-io/ip-finder-python ipfinder-io
PHP Released ipfinder-io/ip-finder-php ipfinder/ipfinder
Ruby Released ipfinder-io/ip-finder-ruby Ipfinder
Perl Released ipfinder-io/ip-finder-perl IO-IPFinder
D Released ipfinder-io/ip-finder-dlag ipfinder
Lua Released ipfinder-io/ip-finder-lua ipfinder
elixir Released ipfinder-io/ip-finder-elixir ipfinder
Dart Released ipfinder-io/ip-finder-dart ipfinder
R Released ipfinder-io/ip-finder-rlang
Swift Released ipfinder-io/ip-finder-swift
Go Released ipfinder-io/ip-finder-go
C# In progress
Rust In progress
Haskell In progress
Erlang In progress
C 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
Meteor (NodeJS - Javascript) Released ipfinder-io/ip-finder-meteor
Spring (Java) In progress
Laravel (PHP) In progress
CodeIgniter (PHP) Released ipfinder-io/codeigniter-ipfinder
cakephp (PHP) Released ipfinder-io/cakephp-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.

If you’ve written a ipfinder library and would like to add it to this page, send an email to [email protected]

Changelog

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

September, 2019

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.
cURL PHP Python Node.js Ruby JAVA Lua dlang Rlang elixir Swift Go Dart CLI