Documentation

Last updated on November 16, 2023
Please always use the following API endpoint api.ipapi.is

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:
  • The API uses IP threat data from various public honeypots
  • 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.

IPv4 Geolocation Database IPv6 Geolocation Database

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.

Download the ASN Database

# 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
Download the Hosting Database

# 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);
}

# API Response Format

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_crawler": 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.88645,
    "longitude": -78.87837,
    "zip": "14205",
    "timezone": "America/New_York",
    "local_time": "2023-11-16T06:24:04-05:00",
    "local_time_unix": 1700133844,
    "is_dst": false
  },
  "elapsed_ms": 0.99
}

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_crawler": 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_crawler - Whether the IP belongs to a crawler / spider / good bot

The field is_crawler is either set to false or, if the IP belongs to a crawler, it is set to a string such as "GoogleBot" or "BingBot".

Some Examples:

This field can be used to check whether the IP address belongs to a search engine crawler / bot that you might want to allow on your website or app. Currently, the following crawlers are detected:

  • TwitterBot
  • GoogleBot
  • BingBot
  • AhrefsBot
  • DuckDuckGoBot
  • FacebookBot
  • PingdomBot
  • RssApiBot
  • StripeWebhook
  • TelegramBot
  • UptimeRobot
  • CommonCrawlBot
  • EmbedlyBot
  • SemRushBot
  • AmazonBot
  • SemanticScholarBot
  • SlackBot
  • Applebot
  • GoogleBotImage
  • APIsGoogle
  • ArchiveBot
  • ByteSpider
  • LinkedInBot
  • ArchiveOrgBot
  • DiscordBot
  • MastodonBot
  • HubSpotBot
  • YouBot
  • YandexBot
  • NextCloudBot
  • PinterestBot
  • SlurpBot
  • MailRuBot
  • Facebookexternalhit
  • ZoomBot
  • BingPreviewBot
  • WhatsAppBot
  • AdsBotGoogle
  • GoogleBotMobile
  • MediapartnersGoogle
  • WordPressBot
  • DuckDuckBot
  • BaiduSpider

# 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 (hosting provider) or not. Here, we have the value true, since 107.174.138.172 belongs to the hosting provider ColoCrossing.

The definition of what constitutes a datacenter (hosting providers) is quite lenient on ipapi.is and includes all of the following categories:

Put differently: Every organization that allows third parties to quickly and anonymously obtain hosting resources or access to IP addresses is considered to be a hosting provider.

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.

List of hosting providers

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

Nevertheless, ipapi.is attempts to be as accurate as possible by using many different sources that publish proxy IP addresses. Example source: firehol_anonymous.netset from the FireHOL project.

# 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. Put differently, ipapi.is cannot reliably detect all VPN exit nodes in the Internet, since the same difficulties that apply to offline proxy detection also apply to VPN detection.

Example source for VPN IP addresses: github.com/X4BNet/lists_vpn

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

Example source for abusive IP addresses: firehol_abusers_1d.netset

# 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 of an 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.88645,
  "longitude": -78.87837,
  "zip": "14205",
  "timezone": "America/New_York",
  "local_time": "2023-11-16T06:24:04-05:00",
  "local_time_unix": 1700133844,
  "is_dst": false
},

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));