IPList FAQ API Blog

IPList.cc - API

URL

A free API is provided which provides details about requested IP addresses. The API is available by sending a GET request to the following URL:

https://iplist.cc/api/IP_ADDRESS

Replace IP_ADDRESS with the actual IP address, e.g.

https://iplist.cc/api/52.178.167.109

A hostname can be provided instead of an IP address, e.g.

https://iplist.cc/api/iplist.cc

The parameter can also be omitted to get information about the remote IP address of the caller, e.g.

https://iplist.cc/api

Return values

The API returns various fields with information about an IP address. Empty fields are always omitted, booleans are always returned. The following fictional example shows the available fields.

Example

{
  "ip": "52.178.167.109",
  "registry": "ARIN",
  "countrycode": "US",
  "countryname": "United States of America",
  "asn": {
    "code": "8075",
    "name": "Microsoft Corporation",
    "route": "52.160.0.0/11"
    "start": "52.160.0.0"
    "end": "52.191.255.255"
    "count": "2097152"
  },
  "spam": false,
  "tor": false,
  "city": "city name"
  "detail": "misc. details"
  "website": [
    "microsoftonline.com"
  ]
}

Fields

ip
The requested and validated IPv4 or IPv6 address.
registry
Regional Internet Registry (RIR) to which this address is assigned. This field contains the name of one of the five official RIRs or the value "PRIVATE" for lan addresses.
countrycode
ISO 3166-2 country code.
countryname
Full country name.
asn
Information about the "Autonomous System Number" (ASN). If information about an ASN is available the following three fields will be provided. Note that the same ASN can refer to multiple non-continguous IP ranges. ASNs can also overlap with other ASNs or be contained within others.
asn code
Numeric ASN code.
asn name
The common name for the ASN.
asn route
IP and CIDR prefix of the ASN.
asn start
IP start address of the ASN.
asn end
IP end address of the ASN.
asn count
Number of IP addresses in the ASN, not all addresses are useable.
spam
Boolean which is true if the provided address occurs on a public spam list, false otherwise.
tor
Boolean which is true if the provided address is a TOR exit node, false otherwise.
city
Name of the city the IP address has been assigned to.
detail
Miscellaneous details about the address, such as information about internet cafes, hotels or businesses.
website
An array with urls which resolve to this IP, limited to max. 500 records.
error
An error message, only provided when the request cannot be answered.

Errors

The API can return an error instead of a list with fields. The following errors may be returned.

ERROR_TOO_MANY_REQUESTS

The API is currently unable to answer your request because you've reached the limit (see the information about limits below).

ERROR_INVALID_IP

An invalid IP adres was provided.

ERROR_HOSTNAME_NOT_FOUND

A hostname is provided but it is not in our database.

ERROR_INVALID_API_CALL

The API cannot process the request.

Integration

Integration of our service into your application is dependent on the programming language. The first step is always to determine the visitor IP address. Popular webservers, like Apache, IIS or Nginx, provided information about visitors in server headers. The headers contain different fields with IP information, when a user is requesting a page through a proxy, one of the following variables may contain the real IP address of the user: HTTP_CLIENT_IP, HTTP_X_FORWARDED, HTTP_X_FORWARDED_FOR. Usually the user IP address is available in the variable REMOTE_ADDR.

ASP.NET
Dim json As String = New Net.WebClient().DownloadString("https://iplist.cc/api/" & Request.ServerVariables("REMOTE_ADDR"))
C#
string json = new System.Net.WebClient().DownloadString("https://iplist.cc/api/" + Request.ServerVariables("REMOTE_ADDR"));
Jquery
$.get('https://iplist.cc/api', function(data) { console.log(data); });
NodeJS
var https = require('https');
https.get('https://iplist.cc/api/2a00:d880:5:509::face', function(res) {
  var body = '';
  res.on('data', function(c) {
    body += c;
  });
  res.on('end', function() {
    console.log(JSON.parse(body));
  });
});
PHP
$ip = json_decode(file_get_contents('http://iplist.cc/api/2a00:d880:5:509::face'));
Python
import requests
ip = requests.get('https://iplist.cc/api/2a00:d880:5:509::face')
print ip.text
Ruby
require 'json'
require 'open-uri'
ip = JSON.parse(open('https://iplist.cc/api/2a00:d880:5:509::face').read)
puts ip

Limits

There is a fair use policy which is high enough so legitimate requests should always be answered. Generally speaking, if you send thousands of requests per second for multiple minutes the API will return an error.