Added support for fraud score

Author: ip2location

LICENSE.TXT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 - 2024 IP2Location.com
+Copyright (c) 2018 - 2025 IP2Location.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -3,7 +3,7 @@
 
 # IP2Proxy Go Package
 
-This package allows user to query an IP address if it was being used as VPN anonymizer, open proxies, web proxies, Tor exits, data center, web hosting (DCH) range, search engine robots (SES), residential proxies (RES), consumer privacy networks (CPN), and enterprise private networks (EPN). It lookup the proxy IP address from **IP2Proxy BIN Data** file. This data file can be downloaded at
+This package allows user to query an IP address if it was being used as VPN anonymizer, open proxies, web proxies, Tor exits, data center, web hosting (DCH) range, search engine robots (SES), residential proxies (RES), consumer privacy networks (CPN), enterprise private networks (EPN) and fraud score. It lookup the proxy IP address from **IP2Proxy BIN Data** file. This data file can be downloaded at
 
 * Free IP2Proxy BIN Data: https://lite.ip2location.com
 * Commercial IP2Proxy BIN Data: https://www.ip2location.com/database/ip2proxy

docs/source/code.md

@@ -12,7 +12,7 @@ Close and clean up the file pointer.
 ```
 
 ```{py:function} PackageVersion()
-Return the database's type, 1 to 10 respectively for PX1 to PX11. Please visit https://www.ip2location.com/databases/ip2proxy for details.
+Return the database's type, 1 to 12 respectively for PX1 to PX12. Please visit https://www.ip2location.com/databases/ip2proxy for details.
 
 :return: Returns the package version.
 :rtype: string
@@ -36,8 +36,8 @@ Return the database's compilation date as a string of the form 'YYYY-MM-DD'.
 Retrieve geolocation information for an IP address.
 
 :param string ipAddress: (Required) The IP address (IPv4 or IPv6).
-:return: Returns the geolocation information in array. Refer below table for the fields avaliable in the array
-:rtype: array
+:return: Returns the geolocation information in an object. Refer below table for the fields avaliable in the object
+:rtype: object
 
 **RETURN FIELDS**
 
@@ -56,4 +56,5 @@ Retrieve geolocation information for an IP address.
 | Threat         |     Security threat reported. |
 | ProxyType      |     Type of proxy. |
 | Provider       |     Name of VPN provider if available. |
+| FraudScore       |     Potential risk score (0 - 99) associated with IP address. |
 ```

docs/source/conf.py

@@ -4,7 +4,7 @@
 # -- Project information
 
 project = 'IP2Proxy Go'
-copyright = '2024, IP2Location'
+copyright = '2025, IP2Location'
 author = 'IP2Location'
 
 release = '0.1.0'

docs/source/index.md

@@ -3,7 +3,7 @@
 
 # IP2Proxy Go Package
 
-This package allows user to query an IP address if it was being used as VPN anonymizer, open proxies, web proxies, Tor exits, data center, web hosting (DCH) range, search engine robots (SES), residential proxies (RES), consumer privacy networks (CPN), and enterprise private networks (EPN). It lookup the proxy IP address from **IP2Proxy BIN Data** file. This data file can be downloaded at
+This package allows user to query an IP address if it was being used as VPN anonymizer, open proxies, web proxies, Tor exits, data center, web hosting (DCH) range, search engine robots (SES), residential proxies (RES), consumer privacy networks (CPN), enterprise private networks (EPN) and fraud score. It lookup the proxy IP address from **IP2Proxy BIN Data** file. This data file can be downloaded at
 
 * Free IP2Proxy BIN Data: <https://lite.ip2location.com>
 * Commercial IP2Proxy BIN Data: <https://www.ip2location.com/database/ip2proxy>

docs/source/quickstart.md

@@ -34,7 +34,7 @@ import (
 )
 
 func main() {
-	db, err := ip2proxy.OpenDB("./IP2PROXY-IP-PROXYTYPE-COUNTRY-REGION-CITY-ISP-DOMAIN-USAGETYPE-ASN-LASTSEEN-THREAT-RESIDENTIAL-PROVIDER.BIN")
+	db, err := ip2proxy.OpenDB("./IP2PROXY-IP-PROXYTYPE-COUNTRY-REGION-CITY-ISP-DOMAIN-USAGETYPE-ASN-LASTSEEN-THREAT-RESIDENTIAL-PROVIDER-FRAUDSCORE.BIN")
 
 	if err != nil {
 		return
@@ -65,6 +65,7 @@ func main() {
 	fmt.Printf("LastSeen: %s\n", all.LastSeen);
 	fmt.Printf("Threat: %s\n", all.Threat)
 	fmt.Printf("Provider: %s\n", all.Provider)
+	fmt.Printf("FraudScore: %s\n", all.FraudScore)
 
 	db.Close()
 }

ip2proxy.go

@@ -1,6 +1,7 @@
 // Package ip2proxy allows user to query an IP address if it was being used as
 // VPN anonymizer, open proxies, web proxies, Tor exits, data center,
-// web hosting (DCH) range, search engine robots (SES) and residential (RES)
+// web hosting (DCH) range, search engine robots (SES), residential (RES),
+// consumer privacy networks (CPN) and enterprise private networks (EPN)
 // by using the IP2Proxy database.
 package ip2proxy
 
@@ -61,6 +62,7 @@ type IP2ProxyRecord struct {
 	LastSeen     string
 	Threat       string
 	Provider     string
+	FraudScore   string
 	IsProxy      int8
 }
 
@@ -69,51 +71,54 @@ type DB struct {
 	f    dbReader
 	meta ip2proxyMeta
 
-	countryPositionOffset   uint32
-	regionPositionOffset    uint32
-	cityPositionOffset      uint32
-	ispPositionOffset       uint32
-	proxyTypePositionOffset uint32
-	domainPositionOffset    uint32
-	usageTypePositionOffset uint32
-	asnPositionOffset       uint32
-	asPositionOffset        uint32
-	lastSeenPositionOffset  uint32
-	threatPositionOffset    uint32
-	providerPositionOffset  uint32
-
-	countryEnabled   bool
-	regionEnabled    bool
-	cityEnabled      bool
-	ispEnabled       bool
-	proxyTypeEnabled bool
-	domainEnabled    bool
-	usageTypeEnabled bool
-	asnEnabled       bool
-	asEnabled        bool
-	lastSeenEnabled  bool
-	threatEnabled    bool
-	providerEnabled  bool
+	countryPositionOffset    uint32
+	regionPositionOffset     uint32
+	cityPositionOffset       uint32
+	ispPositionOffset        uint32
+	proxyTypePositionOffset  uint32
+	domainPositionOffset     uint32
+	usageTypePositionOffset  uint32
+	asnPositionOffset        uint32
+	asPositionOffset         uint32
+	lastSeenPositionOffset   uint32
+	threatPositionOffset     uint32
+	providerPositionOffset   uint32
+	fraudScorePositionOffset uint32
+
+	countryEnabled    bool
+	regionEnabled     bool
+	cityEnabled       bool
+	ispEnabled        bool
+	proxyTypeEnabled  bool
+	domainEnabled     bool
+	usageTypeEnabled  bool
+	asnEnabled        bool
+	asEnabled         bool
+	lastSeenEnabled   bool
+	threatEnabled     bool
+	providerEnabled   bool
+	fraudScoreEnabled bool
 
 	metaOK bool
 }
 
 var defaultDB = &DB{}
 
-var countryPosition = [12]uint8{0, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3}
-var regionPosition = [12]uint8{0, 0, 0, 4, 4, 4, 4, 4, 4, 4, 4, 4}
-var cityPosition = [12]uint8{0, 0, 0, 5, 5, 5, 5, 5, 5, 5, 5, 5}
-var ispPosition = [12]uint8{0, 0, 0, 0, 6, 6, 6, 6, 6, 6, 6, 6}
-var proxyTypePosition = [12]uint8{0, 0, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2}
-var domainPosition = [12]uint8{0, 0, 0, 0, 0, 7, 7, 7, 7, 7, 7, 7}
-var usageTypePosition = [12]uint8{0, 0, 0, 0, 0, 0, 8, 8, 8, 8, 8, 8}
-var asnPosition = [12]uint8{0, 0, 0, 0, 0, 0, 0, 9, 9, 9, 9, 9}
-var asPosition = [12]uint8{0, 0, 0, 0, 0, 0, 0, 10, 10, 10, 10, 10}
-var lastSeenPosition = [12]uint8{0, 0, 0, 0, 0, 0, 0, 0, 11, 11, 11, 11}
-var threatPosition = [12]uint8{0, 0, 0, 0, 0, 0, 0, 0, 0, 12, 12, 12}
-var providerPosition = [12]uint8{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 13}
-
-const moduleVersion string = "4.0.1"
+var countryPosition = [13]uint8{0, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3}
+var regionPosition = [13]uint8{0, 0, 0, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4}
+var cityPosition = [13]uint8{0, 0, 0, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5}
+var ispPosition = [13]uint8{0, 0, 0, 0, 6, 6, 6, 6, 6, 6, 6, 6, 6}
+var proxyTypePosition = [13]uint8{0, 0, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2}
+var domainPosition = [13]uint8{0, 0, 0, 0, 0, 7, 7, 7, 7, 7, 7, 7, 7}
+var usageTypePosition = [13]uint8{0, 0, 0, 0, 0, 0, 8, 8, 8, 8, 8, 8, 8}
+var asnPosition = [13]uint8{0, 0, 0, 0, 0, 0, 0, 9, 9, 9, 9, 9, 9}
+var asPosition = [13]uint8{0, 0, 0, 0, 0, 0, 0, 10, 10, 10, 10, 10, 10}
+var lastSeenPosition = [13]uint8{0, 0, 0, 0, 0, 0, 0, 0, 11, 11, 11, 11, 11}
+var threatPosition = [13]uint8{0, 0, 0, 0, 0, 0, 0, 0, 0, 12, 12, 12, 12}
+var providerPosition = [13]uint8{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 13, 13}
+var fraudScorePosition = [13]uint8{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 14}
+
+const moduleVersion string = "4.1.0"
 
 var maxIPV4Range = uint128.From64(4294967295)
 var maxIPV6Range = uint128.From64(0)
@@ -139,8 +144,9 @@ const as uint32 = 0x00400
 const lastSeen uint32 = 0x00800
 const threat uint32 = 0x01000
 const provider uint32 = 0x02000
+const fraudScore uint32 = 0x04000
 
-const all uint32 = countryShort | countryLong | region | city | isp | proxyType | isProxy | domain | usageType | asn | as | lastSeen | threat | provider
+const all uint32 = countryShort | countryLong | region | city | isp | proxyType | isProxy | domain | usageType | asn | as | lastSeen | threat | provider | fraudScore
 
 const msgNotSupported string = "NOT SUPPORTED"
 const msgInvalidIP string = "INVALID IP ADDRESS"
@@ -446,6 +452,10 @@ func OpenDBWithReader(reader dbReader) (*DB, error) {
 		db.providerPositionOffset = uint32(providerPosition[dbt]-2) << 2
 		db.providerEnabled = true
 	}
+	if fraudScorePosition[dbt] != 0 {
+		db.fraudScorePositionOffset = uint32(fraudScorePosition[dbt]-2) << 2
+		db.fraudScoreEnabled = true
+	}
 
 	db.metaOK = true
 
@@ -484,6 +494,7 @@ func loadMessage(mesg string) IP2ProxyRecord {
 	x.LastSeen = mesg
 	x.Threat = mesg
 	x.Provider = mesg
+	x.FraudScore = mesg
 	x.IsProxy = -1
 
 	return x
@@ -586,6 +597,12 @@ func (d *DB) GetProvider(ipAddress string) (string, error) {
 	return data.Provider, err
 }
 
+// GetFraudScore will return the fraud score of the queried IP address.
+func (d *DB) GetFraudScore(ipAddress string) (string, error) {
+	data, err := d.query(ipAddress, fraudScore)
+	return data.FraudScore, err
+}
+
 // IsProxy checks whether the queried IP address was a proxy. Returned value: -1 (errors), 0 (not a proxy), 1 (a proxy), 2 (a data center IP address or search engine robot).
 func (d *DB) IsProxy(ipAddress string) (int8, error) {
 	data, err := d.query(ipAddress, isProxy)
@@ -774,6 +791,12 @@ func (d *DB) query(ipAddress string, mode uint32) (IP2ProxyRecord, error) {
 				}
 			}
 
+			if mode&fraudScore != 0 && d.fraudScoreEnabled {
+				if x.FraudScore, err = d.readStr(d.readUint32Row(row, d.fraudScorePositionOffset)); err != nil {
+					return x, err
+				}
+			}
+
 			if x.CountryShort == "-" || x.ProxyType == "-" {
 				x.IsProxy = 0
 			} else {