Lua IP Address Database Reader Documentation

Lua Flat File IP Address Reputation Reader

The IPQS Flat File Database Reader brings a new standard of performance and compression to our IP reputation and geolocation services. Setting up and using the reader can be achieved in minutes and provides access to our proxy detection database.

Installation

The ipqs-db-reader package is available as a "rock" from LuaRocks.

luarocks install ipqs-db-reader

You may then open the included documentation, if you wish.

luarocks doc ipqs-db-reader

The source code as well as examples for IPv4 and IPv6 lookups are available in our Github repository.

Usage

Using our flat file database system to lookup an IP address is simple:

local ip = "8.8.0.0"

local reader = require("ipqs.reader")
local fileReader, readError = reader.open("IPQualityScore-IP-Reputation-Database-IPv4.ipqs")
if readError then
    error(readError)
end

local record = require("ipqs.record")
local rec, err = record.fetch(fileReader, ip) -- returns a "record" table (see documentation below)
if err then
    error(err)
end

if rec.is_proxy then
    print(ip .. " is a proxy!")
end

Record Table Indices

See the table below for the boolean values and default columns included in most files. Your particular file may have columns in addition to the default columns. Arbitrary columns may be queried with the record:get("ColumnName") syntax. Speak with your IPQualityScore representative if you have any questions about your flat file database.

Field	Type	Description
record.is_proxy	boolean	Is this IP address suspected to be a proxy? (SOCKS, Elite, Anonymous, VPN, Tor, etc.)
record.is_vpn	boolean	Is this IP suspected of being a VPN connection? This can include data center ranges which can become active VPNs at any time. The "proxy" status will always be true when this value is true.
record.is_tor	boolean	Is this IP suspected of being a TOR connection? This can include previously active TOR nodes and exits which can become active TOR exits at any time. The "proxy" status will always be true when this value is true.
record.is_crawler	boolean	Is this IP associated with being a confirmed crawler from a mainstream search engine such as Googlebot, Bingbot, Yandex, etc. based on hostname or IP address verification.
record.is_bot	boolean	Indicates if bots or non-human traffic has recently used this IP address to engage in automated fraudulent behavior. Provides stronger confidence that the IP address is suspicious.
record.recent_abuse	boolean	This value will indicate if there has been any recently verified abuse across our network for this IP address. Abuse could be a confirmed chargeback, compromised device, fake app install, or similar malicious behavior within the past few days.
record.is_blacklisted	boolean	This value will indicate if the IP has been blacklisted by any 3rd party agency for spam, abuse or fraud.
record.is_private	boolean	This value will indicate if the IP is a private, non-routable IP address.
record.is_mobile	boolean	This value will indicate if the IP is likely owned by a mobile carrier.
record.has_open_ports	boolean	This value will indicate if the IP has recently had open (listening) ports.
record.is_hosting_provider	boolean	This value will indicate if the IP is likely owned by a hosting provider or is leased to a hosting company.
record.active_vpn	boolean	Identifies active VPN connections used by popular VPN services and private VPN servers.
record.active_tor	boolean	Identifies active TOR exits on the TOR network.
record.public_access_point	boolean	Indicates if this IP is likely to be a public access point such as a coffee shop, college or library.
record.connection_type	string	Classification of the IP address connection type as "Residential", "Corporate", "Education", "Mobile", "Data Center", or "Unknown".
record.abuse_velocity	string	How frequently the IP address is engaging in abuse across the IPQS threat network. Values can be "high", "medium", "low", or "none".
record.Country	string	Two character country code of IP address or "N/A" if unknown.
record.City	string	City of IP address if available or "N/A" if unknown.
record.ISP	string	ISP if one is known. Otherwise "N/A".
record.Organization	string	Organization if one is known. Can be parent company or sub company of the listed ISP. Otherwise "N/A".
record.ASN	integer	Autonomous System Number if one is known. 0 if nonexistent.
record.Timezone	string	Timezone of IP address if available or "N/A" if unknown.
record.Latitude	float	Latitude of IP address if available or 0.00 if unknown.
record.Longitude	float	Longitude of IP address if available or 0.00 if unknown.
record.ZeroFraudScore	integer	The "strictness" = 0 fraud score for this IP address. See Proxy Detection API Docs for details about our fraud scores and the strictness parameter.
record.OneFraudScore	integer	The "strictness" = 1 fraud score for this IP address. See Proxy Detection API Docs for details about our fraud scores and the strictness parameter.

Usage Notes

Each database only holds either IPv4 or IPv6 data. Therefore you may need two instances of the reader available depending on your use case.
Due to the nature of IEEE-754 floating-point representation, floating-point values may display misleading precision. For example, 32.51 when converted to little endian hexadecimal representation is: `0x3D0A0242`, which if interpreted literally actually represents 32.509998321533 in Lua. Our Latitude and Longitude values should be interpreted as accurate to 2 (rounded) decimal places, e.g. string.format("%.2f", record:get("Latitude"))