Documentation
Modified on August 29, 2023
ipapi.is provides useful meta-information for IPv4 and IPv6 addresses.
For example, the API response includes the organization of the IP address, ASN meta data, geolocation
intelligence and the raw WHOIS data for the IP address.
Furthermore, the API response allows to derive security information for each IP address,
for example whether an IP address belongs to
- a hosting provider (
is_datacenter
)
- is a TOR exit node (
is_tor
)
- if an IP address is a proxy server exit node (socks4, socks5 or http proxy) (
is_proxy
)
- or is a VPN exit node (
is_vpn
)
- or belongs to an IP address that committed abusive actions (
is_abuser
)
The API strongly emphasizes hosting detection. A complicated hosting
detection
algorithm was developed to achieve a high detection rate. Thousands of different hosting providers around the
globe are tracked.
WHOIS records, public IP ranges from hosting providers and a proprietary hosting discovery algorithm
are used to decide whether an IP address belongs to a hosting provider or not.
ipapi.is claims to have the best hosting
detection
algorithm in the IP address provider space. This is mainly achieved by downloading and analyzing the
websites of all major
organizations that own IP addresses in the Internet.
ipapi.is furthermore includes accurate and rich ASN meta data.
Additionally,
the API includes raw WHOIS data
for each active ASN. API fields such as the type
field included in the
company
or asn
output object are derived by analyzing the company (organization)
that owns
the autonomous system or IP range. ipapi.is distinguishes between the
following
company (organization)
types:
hosting
- The ASN or network is owned by a hosting provider (Example: 37.148.167.137)
education
- The ASN or network belongs to a university or other kind of educational
institution (Example: 128.146.65.112)
-
government
- The ASN or network belongs to a governmental institution (Example: 192.91.184.0)
banking
- The ASN or network belongs to a banking / financial institution (Example:
199.67.175.0)
isp
- The ASN or network belongs to a Internet Service Provider (ISP)
(Example: 108.15.237.36)
business
- If the type is not one of the above, the type is the generic
business
type (Example:
17.133.85.230)
#
Quickstart
In order to lookup any IP address, use the following API endpoint: https://api.ipapi.is?q=3.5.140.2
Lookup your own IP address by omitting the query string (no q
parameter): https://api.ipapi.is
Usage with JavaScript:
fetch('https://api.ipapi.is?q=23.236.48.55')
.then(res => res.json())
.then(res => console.log(res));
Usage with curl
:
curl 'https://api.ipapi.is?q=32.5.140.2'
#
Data Sources
ipapi.is uses of the following sources for API data:
- Public WHOIS records from Regional Internet Registries (RIR's) such as RIPE
NCC, APNIC, ARIN. For
privacy reasons,
the public and downloadable WHOIS database from the five RIR's is often not complete. Therefore, millions
of IP
ranges and ASN's need to be periodically queried with a
whois
client in order to keep
ipapi.is up to date.
- Public BGP routing table data is used in order to
source
ASN data and to get the routes (prefixes) for each active ASN.
- Public IP blocklists such as firehol/blocklist-ipset or stamparm/ipsum are used to source the
is_abuser
flag.
- The API uses a proprietary datacenter/hosting detection algorithm. Accurate hosting detection is
essentially achieved by aggregating data from many different sources:
- Manually labelling organizations as hosting providers (not efficient)
- Automatically labelling organizations as hosting providers based on the organization name,
organization domain, organization website with HTML text and HTML meta tags (efficient, but a lot of
false
positives and requires scraping/crawling of millions of organization websites)
- Using self-published IP ranges from large cloud providers such as:
- Considering open source projects that try to find hosting IP addresses such as github.com/client9/ipcat, github.com/Umkus/ip-index or https://github.com/X4BNet/lists_vpn
- The API uses IP threat data from various public honeypots including proxy and VPN data from proxydetect.live
- A proprietary geolocation
database was built from scratch. Geolocation data is mainly sourced from WHOIS
data.
For example, some Regional Internet Registries such
as APNIC support the
geofeed
and geoloc
property in WHOIS records.
RIPE NCC also
added support for the geoloc
attribute as of 2016.
#
API Servers
ipapi.is is currently running in two different locations:
#
API Features
- Ready for production: This API can be used in production and is stable. Currently,
ipapi.is is hosted in two different geographical locations (Germany and US
East) in order to reduce end-user latency. The API can consume millions of daily
requests
and is updated daily (At least once per week).
- Accuracy: The only really trustful IP Address data is WHOIS data that originates from
Regional Internet
Registries such as RIPE NCC or ARIN. Therefore, ipapi.is follows a
WHOIS first approach. IP data from third party providers can never be fully trusted.
- Many hosting/cloud providers supported: Thousands
of different hosting providers and counting - From Huawei Cloud Service to ServerMania Inc. Find out
whether the IP address is hosted by looking at the
is_datacenter
property!
- Always updated: The API database is automatically updated at least once per week.
- ASN support: The API provides autonomous system information for each looked up IP
address.
- Company Support: The API provides organizational information for each looked up IP
address.
- Bulk IP Lookups: You can query up to 100 IP addresses per API call.
- Offline API Usage (Download): You can download the full ipapi.is package and host it in your own infrastructure. See the pricing
page for more information.
#
Geolocation Database
ipapi.is is a geolocation data provider. The Geolocation
Database is
provided for free for download and is used as main data source in the commercial ipapi.is API. The database includes geolocation information
for a large part
of the
IPv4 address space and a many IPv6 networks. The geolocation database is updated several times per week. The
accuracy of
the geolocation data is high for country level accuracy. It is not
recommended to
rely on city level geolocation accuracy for mission critical applications.
The geolocation
database is provided as large CSV file with the following fields:
ip_version
- Either 4
(IPv4) or 6
(IPv6). Determines the IP type
of the
network. Example: "4"
-
start_ip
- The first IP address of the network range. Example:
"44.31.140.0"
-
end_ip
- The last IP address of the network range. Example: "44.31.140.255"
continent
- The continent as two letter code. Example:
"NA"
country_code
- The ISO 3166-1 alpha-2
country code to which the IP
address belongs. This is the country specific geolocation of the IP address. Example:
"US"
country
- The full name of the country. Example:
"United States"
state
- The state / administrative area for the queried IP address. Example:
"California"
city
- The city to which the IP address belongs. Example:
"Fremont"
zip
- The postal code (zip code) for this IP. Example:
"94720"
timezone
- The timezone for this IP. Example:
"America/Los_Angeles"
latitude
- The geographical latitude for the IP address. Example:
"37.54827"
longitude
- The geographical longitude for the IP address. Example:
"-121.98857"
accuracy
- Geolocation information is not always accurate. For that reason, there is an
accuracy
number that gives an estimate of how accurate the provided geolocation information
is.
Entries with accuracy 1 have the highest accuracy, rows with
accuracy 4
have
the
least accurate information.
accuracy = 1
- Very high geolocation accuracy. You can rely the data to be
accurate to
the city level.
accuracy = 2
- High geolocation accuracy. You can usually rely the data to be
accurate to
the city level.
accuracy = 3
- Medium geolocation accuracy. You can not rely the data to be
accurate to
the city level.
accuracy = 4
- Low geolocation accuracy. Usually the data is accurate to the country
level.
accuracy = 5
- Very low geolocation accuracy. The data should be accurate to the
country level.
ipVersion,network,continent,country_code,country,state,city,zip,timezone,latitude,longitude,accuracy
ipv4,204.62.153.0 - 204.62.154.255,NA,US,United States,Ohio,Dayton,45412,America/New_York,39.75895,-84.19161,2
ipv4,131.78.0.0 - 131.78.255.255,NA,US,United States,Ohio,Columbus,43215,America/New_York,39.96118,-82.99879,4
ipv4,64.112.107.0 - 64.112.107.255,NA,US,United States,Texas,Crosbyton,79357,America/Chicago,33.66008,-101.23793,2
ipv4,192.172.223.0 - 192.172.223.255,NA,US,United States,Colorado,Boulder,80544,America/Denver,40.01499,-105.27055,1
ipv4,192.68.53.0 - 192.68.66.255,NA,CA,Canada,Ontario,Ottawa,K2P,America/Toronto,45.41117,-75.69812,4
ipv4,173.205.200.0 - 173.205.203.255,NA,US,United States,Indiana,Swayzee,46986,America/Indiana/Indianapolis,40.50837,-85.82554,2
ipv4,67.219.189.0 - 67.219.191.255,NA,CA,Canada,Ontario,Ottawa,K2P,America/Toronto,45.41117,-75.69812,3
ipv4,72.18.221.0 - 72.18.221.255,NA,US,United States,Florida,Panama City,32466,America/Chicago,30.15946,-85.65983,1
ipv4,23.153.216.0 - 23.153.216.255,NA,US,United States,Florida,Miami,33299,America/New_York,25.77427,-80.19366,2
#
ASN Database
For offline ASN data access, the ASN Database is
provided for download. The ASN database includes all assigned and allocated AS numbers by IANA and
respective meta
information. The database is updated several times per week. For active ASN's (at least one route/prefix
assigned to the AS), the database includes rich meta information. For example, the provided information for
the ASN 50673
would be:
{
"asn": 50673,
"descr": "SERVERIUS-AS, NL",
"country": "nl",
"active": true,
"org": "Serverius Holding B.V.",
"domain": "serverius.net",
"abuse": "abuse@serverius.net",
"type": "hosting",
"created": "2010-09-07",
"updated": "2022-11-15",
"rir": "ripe",
"whois": "https://api.ipapi.is?whois=AS50673",
"prefixes": [
"5.56.133.0/24",
"5.59.188.0/22",
// ...
"212.80.216.0/22",
"217.18.90.0/24",
"217.65.131.0/24"
],
"prefixesIPv6": [
"2001:67c:b0::/48",
"2a00:1ca8::/32",
// ...
"2a0c:480::/32",
"2a0e:c9c0::/29",
"2a0f:4a80::/48"
],
"elapsed_ms": 0.23
}
The database is in JSON format. The key is the ASN as int
and the value is an object with AS
meta information such as the one above.
#
How to download & parse the ASN database?
Download and unzip the ASN database:
cd /tmp
curl -O https://ipapi.is/data/fullASN.json.zip
unzip fullASN.json.zip
And parse with NodeJS:
let asnDatabase = require('./fullASN.json');
for (let asn in asnDatabase) {
console.log(asn, asnDatabase[asn]);
}
#
Hosting IP Ranges Database
Furthermore, the Hosting IP Ranges Database is provided for offline and scalable access.
This database contains all known datacenter IP ranges of the Internet. A proprietary algorithm was developed
to determine if a network belongs to a hosting provider.
The file format of the database is tab separated text file (.tsv), where each line of the file contains the
company
, network
and domain
of the hosting provider.
Example excerpt of the database:
Linode, LLC 178.79.160.0 - 178.79.167.255 www.linode.com
OVH Sp. z o. o. 178.32.191.0 - 178.32.191.127 www.ovh.com
myLoc managed IT AG 46.245.176.0 - 46.245.183.255 www.myloc.de
#
How to download & parse the Hosting IP Ranges Database?
Download and unzip the Hosting Ranges database:
cd /tmp
curl -O https://ipapi.is/data/hostingRanges.tsv.zip
unzip hostingRanges.tsv.zip
And parse with nodejs:
const fs = require('fs');
let hostingRanges = fs.readFileSync('hostingRanges.tsv').toString().split('\n');
for (let line of hostingRanges) {
let [company, network, domain] = line.split('\t');
console.log(company, network, domain);
}
The API output format is explained best by walking through an example. Most of the returned API output
information is
self-explanatory.
The API example lookup below is how a typical API response looks like. The IP 107.174.138.172
was queried with the API
call https://api.ipapi.is?q=107.174.138.172:
{
"ip": "107.174.138.172",
"rir": "ARIN",
"is_bogon": false,
"is_mobile": false,
"is_datacenter": true,
"is_tor": true,
"is_proxy": true,
"is_vpn": false,
"is_abuser": true,
"company": {
"name": "ColoCrossing",
"domain": "www.colocrossing.com",
"type": "hosting",
"network": "107.172.0.0 - 107.175.255.255",
"whois": "https://api.ipapi.is/?whois=107.172.0.0"
},
"datacenter": {
"datacenter": "ColoCrossing",
"domain": "https://www.colocrossing.com/",
"network": "107.172.0.0-107.175.255.255"
},
"asn": {
"asn": 36352,
"route": "107.174.138.0/24",
"descr": "AS-COLOCROSSING, US",
"country": "us",
"active": true,
"org": "ColoCrossing",
"domain": "www.colocrossing.com",
"abuse": "abuse@colocrossing.com",
"type": "hosting",
"created": "2005-12-12",
"updated": "2013-01-08",
"rir": "arin",
"whois": "https://api.ipapi.is/?whois=AS36352"
},
"location": {
"continent": "NA",
"country": "United States",
"country_code": "US",
"state": "New York",
"city": "Buffalo",
"latitude": 42.8825,
"longitude": -78.8788,
"zip": "14202",
"timezone": "America/New_York",
"local_time": "2023-07-16T08:09:03-04:00",
"local_time_unix": 1689509343,
"is_dst": true
},
"elapsed_ms": 0.96
}
In the following sections, the different parts of the API response are explained in-depth.
In general, the API output can be divided into several distinctive parts:
- Top Level API Output - Generic output and threat intelligence information for the queried IP address.
- The
datacenter
object - The datacenter
object is only present if the queried
IP address belongs to a hosting provider. The datacenter
object contains meta information for
the hosting provider / datacenter.
- The
company
object - Most IP addresses belong to an organization / company. The
company
object contains meta information about the organization that owns (or has administrative
control over)
the queried IP
address.
- The
asn
object - Most IP addresses belong to an Autonomous System (AS). The
asn
object
holds meta information about the Autonomous System (AS).
- The
location
object - It is often possible to geographically locate IP addresses. The
location
object contains geographical information for the queried IP address. Put
differently, the location
object answers the question in what part of the earth the IP
address is used.
#
Top Level API Output
The top level API output looks as follows for the IP address 107.174.138.172
:
{
"ip": "107.174.138.172",
"rir": "ARIN",
"is_bogon": false,
"is_mobile": false,
"is_datacenter": true,
"is_tor": true,
"is_proxy": true,
"is_vpn": false,
"is_abuser": true,
}
The explanation for the top level API fields is as follows:
#
ip
- The API query
The field ip
has datatype string
.
This field represents the IP address that was looked up. In the example above it was
107.174.138.172
.
If no IP address was specified (Example: https://api.ipapi.is), the
client's own IP address is looked up and the field ip
is set to the client's public IP address.
#
rir
- The Regional Internet Registry (RIR) for this IP
The field rir
has datatype string
.
It specifies to which Regional Internet
Registry (RIR) the IP address belongs. Here it belongs to ARIN
, which is the RIR
responsible
for North America. In total, there exist five different RIRs for different areas of the world:
Figure 1: The five different Regional Internet Registries (Source)
#
is_bogon
- Whether the IP is bogon (non routable)
The field is_bogon
has datatype boolean
.
It determines if the IP address is bogon. Bogon IP
Addresses is the set of IP Addresses not assigned/allocated to IANA and any RIR (Regional Internet
Registry). For example, the loopback IP 127.0.0.1
is a special/bogon IP address. The IP address
107.174.138.172
is not bogon, hence it is set to false
here.
In general, there is no good reason to query bogon IP addresses, since they are local or special IP
addresses
that exist in every local network and don't have a special meaning in the Internet.
#
is_mobile
- Whether the IP is mobile (Belongs to a mobile ISP)
The field is_mobile
has datatype boolean
.
It determines if the IP address belongs to a mobile Internet Service Provider such as
AT&T Wireless
or T-Mobile
. For security purposes, it is often beneficial to know
whether an IP address belongs to a mobile ISP or not.
For example, Carrier-grade NATs are often used
in mobile
networks and as a consequence many distinct clients can have the same public IP address.
This means that rate limiting or banning mobile IP addresses is not a good idea, since it will also block
legitimate clients that share the same mobile, public IP address.
There are other reasons why it is important to know whether a IP originates from a mobile ISP, such as:
- Some services should only be accessible to mobile clients
- Mobile clients often have reduced Internet speed and it is beneficial to know this for service providers
in advance
The IP address
107.174.138.172
does not belong to a mobile ISP, hence it is set to false
here.
#
is_datacenter
- Whether the IP belongs
to a Hosting Provider
The field is_datacenter
has datatype boolean
.
It specifies whether the IP address belongs to a datacenter or not. Here, we have the value
true
, since 107.174.138.172
belongs to the hosting provider
ColoCrossing
.
If the IP address belongs to a datacenter, then there will always also be the datacenter object present in the API output.
The datacenter / hosting detection quality of ipapi.is is one of it's core
strengths. If this value is true, you can rely that the IP address belongs to a hosting provider.
For a full list of hosting providers, click on the button below.
#
is_tor
- Whether the IP is a TOR Exit Node
The field is_tor
has datatype boolean
.
If the field is_tor
is true, the IP address is a TOR exit node. This is the case here.
TOR exit node detection is very accurate, so you can rely on the value of is_tor
. The API
detects
most TOR
exit nodes reliably.
If the is_tor
attribute is true
, it is recommended to either challenge the
client with this IP address with a captcha or to block the client from accessing critical resources.
Why is
that? The TOR network is often used by cyber criminals for malicious actions and if you are running a
critical service, you might want to prohibit TOR clients from accessing it.
#
is_proxy
- Whether the IP is a Proxy Exit
Node
The field is_proxy
has datatype boolean
.
The field determines whether the IP address is a proxy. This is not the case here. In general, the flag
is_proxy
only covers a subset of all proxies in the Internet. Put differently, ipapi.is cannot reliably detect residential and mobile proxies.
In general, proxy and VPN detection that follows an offline based approach is not very accurate. Offline
means IP address data
stored
in files or databases as it is the case with ipapi.is or any other similar
service.
Why is this so?
If a threat actor purchases a cheap hosting instance and installs a proxy server on it, how can any offline
proxy database contain the information that the instance is used as proxy server? This information can only
be
manifested over time, after the threat actor used the instance on websites or honeypots. So in best case
scenario, those
proxy
databases are outdated, lag behind or are simply false.
For that reason, proxy and VPN's can only be detected by observing the network behavior in live sessions. proxydetect.live offers live proxy and VPN detection as a service for
online businesses.
#
is_vpn
- Whether the IP is a VPN Exit Node
The field is_vpn
has datatype boolean
.
The field determines if the IP address is a VPN. This is not the case with the IP
107.174.138.172
.
In general, the flag is_vpn
only covers a subset of all VPN's in
the Internet. It is not possible to detect all VPN exit nodes passively. Put differently, ipapi.is cannot reliably detect VPN exit nodes, since the same
difficulties that apply to offline proxy detection also apply to VPN detection.
Robust VPN detection in live traffic can be achieved by proxydetect.live.
#
is_abuser
- Whether the IP committed abusive
actions
The field is_abuser
has datatype boolean
.
The field is_abuser
is true if the IP address committed abusive actions, which was the case
with 107.174.138.172
. Various IP blocklists and threat intelligence feeds are used to populate
the is_abuser
flag.
Open source and proprietary block lists are used in the API to populate the is_abuser
flag.
There is no further differentiation of the abusive action, the IP could have been a virus, bot, crawler,
scraper or worm.
If the is_abuser
attribute is true
, it is recommended to either challenge the
client with this IP address with a captcha or to block the client from accessing critical resources.
#
elapsed_ms
- How much internal processing
time the API lookup took
The field elapsed_ms
has datatype float
.
The field stores how much internal processing time was spent in milliseconds (ms) handling the API query.
This lookup only took
0.9ms
, which is quite fast.
On average, IP lookups on ipapi.is take around 1.2ms
of
processing time.
#
The datacenter
object
Example API output for the datacenter
object:
"datacenter": {
"datacenter": "ColoCrossing",
"domain": "www.colocrossing.com",
"network": "107.172.0.0 - 107.175.255.255"
},
If the IP address belongs to a datacenter/hosting provider, the API response will include a
datacenter
object with at least the following attributes:
datacenter
- string
- to which datacenter the IP address belongs. For a full
list of datacenters, check the hosting providers table page.
In
this case, the datacenter's name is ColoCrossing
.
domain
- string
- The domain name of the hosting provider company
network
- string
- the network this IP address belongs to (In the above case:
107.172.0.0 - 107.175.255.255
)
Most IP's don't belong to a hosting provider. In those cases, the datacenter
object will not
be present in the API output.
For a couple of large cloud providers, such as Google Cloud, Amazon AWS, DigitalOcean or Microsoft Azure
(and many others), the datacenter
object is more detailed.
Amazon AWS example:
{
"ip": "3.5.140.2",
"datacenter": {
"datacenter": "Amazon AWS",
"network": "3.5.140.0/22",
"region": "ap-northeast-2",
"service": "EC2",
"network_border_group": "ap-northeast-2"
}
}
DigitalOcean example:
{
"ip": "167.99.241.130",
"datacenter": {
"datacenter": "DigitalOcean",
"code": "60341",
"city": "Frankfurt",
"state": "DE-HE",
"country": "DE",
"network": "167.99.240.0/20"
},
}
Linode example:
{
"ip": "72.14.182.54",
"datacenter": {
"datacenter": "Linode",
"name": "US-TX",
"city": "Richardson",
"country": "US",
"network": "72.14.182.0/24"
},
}
#
The company
object
Example API output for the company
object:
"company": {
"name": "ColoCrossing",
"domain": "www.colocrossing.com",
"type": "hosting",
"network": "107.172.0.0 - 107.175.255.255",
"whois": "https://api.ipapi.is?whois=107.172.0.0"
},
Most IP addresses can be associated with an organization or company. The API uses WHOIS
information to infer which organization is the administrative owner of a certain IP address.
The owner or administrative responsible organization responsible for a IP address is stored in the databases
of the five
Regional
Internet
Registies (RIR'rs). For
example, IP
address ownership
in RIPE NCC is handled with inetnum
(IPv4)
and inet6num
(IPv6)
objects. In ARIN, IP address ownership
can be inferred from NetRange objects.
Since the example IP 107.174.138.172
falls into the administrative realm of ARIN, the
corresponding WHOIS record is obtained with whois -h whois.arin.net 107.174.138.172
and yields:
NetRange: 107.172.0.0 - 107.175.255.255
CIDR: 107.172.0.0/14
NetName: CC-17
NetHandle: NET-107-172-0-0-1
Parent: NET107 (NET-107-0-0-0-0)
NetType: Direct Allocation
OriginAS: AS36352
Organization: ColoCrossing (VGS-9)
RegDate: 2013-12-27
Updated: 2013-12-27
Ref: https://rdap.arin.net/registry/ip/107.172.0.0
OrgName: ColoCrossing
OrgId: VGS-9
Address: 325 Delaware Avenue
Address: Suite 300
City: Buffalo
StateProv: NY
PostalCode: 14202
Country: US
RegDate: 2005-06-20
Updated: 2023-05-11
Ref: https://rdap.arin.net/registry/entity/VGS-9
OrgAbuseHandle: ABUSE3246-ARIN
OrgAbuseName: Abuse
OrgAbusePhone: +1-800-518-9716
OrgAbuseEmail: abuse@colocrossing.com
OrgAbuseRef: https://rdap.arin.net/registry/entity/ABUSE3246-ARIN
OrgTechHandle: NETWO882-ARIN
OrgTechName: Network Operations
OrgTechPhone: +1-800-518-9716
OrgTechEmail: support@colocrossing.com
OrgTechRef: https://rdap.arin.net/registry/entity/NETWO882-ARIN
OrgNOCHandle: NETWO882-ARIN
OrgNOCName: Network Operations
OrgNOCPhone: +1-800-518-9716
OrgNOCEmail: support@colocrossing.com
OrgNOCRef: https://rdap.arin.net/registry/entity/NETWO882-ARIN
The company
object is sourced from inetnum
or NetRange
WHOIS objects.
The
OrgName
from the WHOIS record above is mapped to the name
attribute of the
the company
object.
Most API lookups will have an
company
object with the following attributes:
name
- string
- The name of the organization (company) obtained from the
corresponding WHOIS database entry
domain
- string
- The domain name of the organization (company)
type
- string
- The type for this organization (company), this is either
hosting
,
education
, government
, banking
, business
or
isp
network
- string
- The network for which the organization (company) has
ownership
whois
- string
- An url to the WHOIS record for the network of this IP
address
#
The asn
object
Example API output for the asn
object:
"asn": {
"asn": 36352,
"route": "107.174.138.0/24",
"descr": "AS-COLOCROSSING, US",
"country": "us",
"active": true,
"org": "ColoCrossing",
"domain": "www.colocrossing.com",
"abuse": "abuse@colocrossing.com",
"type": "hosting",
"created": "2005-12-12",
"updated": "2013-01-08",
"rir": "arin",
"whois": "https://api.ipapi.is?whois=AS36352"
},
Most IP addresses can be associated with an Autonomous System (AS). Similar to the company
object, the
core data to populate the
asn
object originates from WHOIS data. For example, in order to find the corresponding
information for ASN 36352, the WHOIS query whois -h whois.arin.net as36352
yields:
ASNumber: 36352
ASName: AS-COLOCROSSING
ASHandle: AS36352
RegDate: 2005-12-12
Updated: 2013-01-08
Comment: http://www.colocrossing.com
Ref: https://rdap.arin.net/registry/autnum/36352
OrgName: ColoCrossing
OrgId: VGS-9
Address: 325 Delaware Avenue
Address: Suite 300
City: Buffalo
StateProv: NY
PostalCode: 14202
Country: US
RegDate: 2005-06-20
Updated: 2023-05-11
Ref: https://rdap.arin.net/registry/entity/VGS-9
OrgAbuseHandle: ABUSE3246-ARIN
OrgAbuseName: Abuse
OrgAbusePhone: +1-800-518-9716
OrgAbuseEmail: abuse@colocrossing.com
OrgAbuseRef: https://rdap.arin.net/registry/entity/ABUSE3246-ARIN
OrgNOCHandle: NETWO882-ARIN
OrgNOCName: Network Operations
OrgNOCPhone: +1-800-518-9716
OrgNOCEmail: support@colocrossing.com
OrgNOCRef: https://rdap.arin.net/registry/entity/NETWO882-ARIN
OrgTechHandle: NETWO882-ARIN
OrgTechName: Network Operations
OrgTechPhone: +1-800-518-9716
OrgTechEmail: support@colocrossing.com
OrgTechRef: https://rdap.arin.net/registry/entity/NETWO882-ARIN
RTechHandle: VIALA-ARIN
RTechName: Vial, Alex
RTechPhone: +1-716-335-9628
RTechEmail: avial@colocrossing.com
RTechRef: https://rdap.arin.net/registry/entity/VIALA-ARIN
RAbuseHandle: ABUSE3246-ARIN
RAbuseName: Abuse
RAbusePhone: +1-800-518-9716
RAbuseEmail: abuse@colocrossing.com
RAbuseRef: https://rdap.arin.net/registry/entity/ABUSE3246-ARIN
RNOCHandle: NETWO882-ARIN
RNOCName: Network Operations
RNOCPhone: +1-800-518-9716
RNOCEmail: support@colocrossing.com
RNOCRef: https://rdap.arin.net/registry/entity/NETWO882-ARIN
RTechHandle: NETWO882-ARIN
RTechName: Network Operations
RTechPhone: +1-800-518-9716
RTechEmail: support@colocrossing.com
RTechRef: https://rdap.arin.net/registry/entity/NETWO882-ARIN
WHOIS data such as the one from above is used to populate the asn
object. For example,
the OrgName
(ColoCrossing) from the WHOIS record above is mapped to name
attribute of the
the asn
object.
The asn
object provides
the following attributes:
asn
- int
- The AS number (ASN)
route
- string
- The IP route (prefix) in CIDR network format
descr
- string
- An informational description of the AS
country
- string
- The origin country of the AS (administratively)
active
- string
- Whether the AS is active (active means that there is at
least one route
administered by the AS)
org
- string
- The organization (Based on WHOIS data) responsible for
this AS
domain
- string
- The domain of the organization to which this AS belongs
abuse
- string
- The email address to which abuse complaints for this
organization should be sent (Based on WHOIS data)
type
- string
- The type for this ASN, this is either hosting
,
education
, government
, banking
, business
or
isp
created
- string
- When the ASN was established (Based on WHOIS data)
updated
- string
- The last time the ASN was updated (Based on WHOIS data)
rir
- string
- To which Regional Internet Registry the ASN belongs
administratively
whois
- string
- An url to the WHOIS information for this ASN
For inactive autonomous systems, most of the above information is not available.
#
The location
object
Example API output for the location
object:
"location": {
"continent": "NA",
"country": "United States",
"country_code": "US",
"state": "New York",
"city": "Buffalo",
"latitude": 42.8825,
"longitude": -78.8788,
"zip": "14202",
"timezone": "America/New_York",
"local_time": "2023-07-16T08:09:03-04:00",
"local_time_unix": 1689509343,
"is_dst": true
}
The API provides geolocation information for the looked up IP address. The location
object
includes the following attributes:
continent
- string
- The continent as two letter code such as NA
for North America
country
- string
- The full name of the country
country_code
- string
- The ISO 3166-1 alpha-2 country code to which the IP
address belongs. This is the country specific geolocation of the IP address.
state
- string
- The state / administrative area for the queried IP address
city
- string
- The city to which the IP address belongs
latitude
- float
- The geographical latitude for the IP address
longitude
- float
- The geographical longitude for the IP address
zip
- string
- The zip code for this IP
timezone
- string
- The timezone for this IP
local_time
- string
- The local time for this IP in human readable format
local_time_unix
- int
- The local time for this IP as unix timestamp
is_dst
- boolean
- Whether daylight saving time (DST) is active in the
geographical region
of this IP address
other
- array
- (Optional) - If there are multiple possible geographical
locations, the attribute other
is included in the API response. It contains an array of ISO 3166-1 alpha-2 country codes which represent the
possible other geolocation countries.
A proprietary
geolocation database was built from scratch in order to source the
location
object.
#
API Endpoints
The IP API currently has two endpoints. One endpoint (GET) handles lookups for single IP addresses, the
other endpoint (POST) handles the lookup of up to 100 IP addresses (Batch lookup).
#
GET Endpoint - Lookup a single IP Address or ASN
This GET endpoint allows to lookup a single IPv4 or IPv6 address by specifying the query parameter
q
. Example: q=142.250.186.110
. You can also lookup ASN numbers by
specifying the query q=AS209103
#
POST Endpoint - Query up to 100 IP Addresses in one
API call
You can also make a bulk API lookup with up to 100 IP addresses (Either IPv4 or IPv6) in one single
request.
- Endpoint - https://api.ipapi.is
- Method -
POST
- Content-Type -
Content-Type: application/json
- Parameter -
ips
- An array of IPv4 and IPv6 addresses to lookup
For example, in order to lookup the IP addresses
162.158.0.0
2406:dafe:e0ff:ffff:ffff:ffff:dead:beef
162.88.0.0
20.41.193.225
You can use the following POST API request with curl
:
curl --header "Content-Type: application/json" \
--request POST \
--data '{"ips": ["162.158.0.0", "2406:dafe:e0ff:ffff:ffff:ffff:dead:beef", "162.88.0.0", "20.41.193.225"]}' \
https://api.ipapi.is
This is how you would make the POST request with JavaScript
using fetch()
:
const IPs = [
'162.158.0.0',
'2406:dafe:e0ff:ffff:ffff:ffff:dead:beef',
'162.88.0.0',
'20.41.193.225'
];
fetch('https://api.ipapi.is', {
method: 'POST',
headers: {
'Accept': 'application/json, text/plain, */*',
'Content-Type': 'application/json'
},
body: JSON.stringify({ ips: IPs })
}).then(res => res.json())
.then(res => console.log(res));