<< Back to Categories

Address Validation

Verify Postal Addresses by API Lookup

Analyze users with Address Verification scoring through a real-time API call. Instantly detect invalid addresses, misformatted user data and typos, and physical addresses that have recently been reported for fraudulent behavior. Physical Address Verification makes verifying users and validating personal user information easy.

Address Validation Example API Request

The example below incorporates scoring a physical address with an IP address. We recommend passing all available billing and shipping variables.

You should pass the user's primary information into the "billing" variables even if a transaction is not taking place. Additional user data can be passed with this request.

Key	Expected Values	Description
billing_address_1	String	User's billing or primary street address part 1.
billing_address_2	String	User's billing or primary street address part 2.
billing_city	String	User's billing or primary city.
billing_region	String	User's billing or primary region or state.
billing_postcode	String / Number	User's billing or primary postcode or zipcode.
billing_country	String	User's billing or primary country name or billing country ISO-Alpha2. (EG: United States or US)
shipping_address_1	String	User's billing or primary street address part 1.
shipping_address_2	String	User's billing or primary street address part 2.
shipping_city	String	User's billing or primary city.
shipping_region	String	User's billing or primary region or state.
shipping_postcode	String / Number	User's billing or primary postcode or zipcode.
shipping_country	String	User's billing or primary country name or shipping country ISO-Alpha2. (EG: United States or US)

EXAMPLE CODE

PHP
PYTHON

// Your API Key.
$key = 'YOUR_API_KEY_HERE';

/*
* Retrieve the user's IP address. 
* You could also pull this from another source such as a database.
* 
* If you use cloudflare change REMOTE_ADDR to HTTP_CF_CONNECTING_IP
*/
$ip = isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : $_SERVER['HTTP_CLIENT_IP'];


// Retrieve additional (optional) data points which help us enhance fraud scores.
$user_agent = $_SERVER['HTTP_USER_AGENT']; 
$user_language = $_SERVER['HTTP_ACCEPT_LANGUAGE'];

// Set the strictness for this query. (0 (least strict) - 3 (most strict))
$strictness = 0;

// You may want to allow public access points like coffee shops, schools, corporations, etc...
$allow_public_access_points = 'true';

// Create parameters array.
$parameters = array(
    'user_agent' => $user_agent,
    'user_language' => $user_language,
    'strictness' => $strictness,
    'allow_public_access_points' => $allow_public_access_points
);

/* User & Transaction Scoring
* Score additional information from a user, order, or transaction for risk analysis
* All transaction parameters are optional, please remove any that are not used
* Non paid actions such as lead generation and user scoring can be substituted into the "billing" or "shipping" variables
* This feature requires a Premium plan or greater
* Premium users can also adjust transaction scoring rules: https://www.ipqualityscore.com/user/transaction/weights
*/

//  All variables are optional - the primary address should be scored in the "billing" variables
    $transaction_parameters = array(
        'billing_address_1' => '',
        'billing_address_2' => '',
        'billing_city' => '',
        'billing_state' => '',
        'billing_zipcode' => '',
        'billing_country' => '',
        'shipping_address_1' => '',
        'shipping_address_2' => '',
        'shipping_city' => '',
        'shipping_state' => '',
        'shipping_zipcode' => '',
        'shipping_country' => ''
);

// Format Parameters
if(is_array($transaction_parameters)){
    $formatted_parameters = http_build_query(array_merge($parameters, $transaction_parameters));
} else {
    $formatted_parameters = http_build_query($parameters);
}

// Create API URL
$url = sprintf(
    'https://www.ipqualityscore.com/api/json/ip/%s/%s?%s', 
    $key,
    $ip, 
    $formatted_parameters
);

// Fetch The Result
$timeout = 5;

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, $timeout);

$json = curl_exec($curl);
curl_close($curl);

// Decode the result into an array.
$result = json_decode($json, true);

// Check to see if our query was successful.
if(isset($result['success']) && $result['success'] === true){
    // NOTICE: If you want to use one of the examples below, remove
    // any lines containing /*, */ and *-, then remove * from any of the
    // the remaining lines.
    
    /*
    *- Address Verification Example 1: We'd like to block users with an invalid physical address or address that was recently used for a fraudulent action
    * 
    * if($result['transaction_details']['valid_billing_address'] === false || $result['transaction_details']['valid_shipping_address'] === false){
    *		exit(header("Location: https://google.com"));
    * }
    */
    
    /*
    *- Address Verification Scoring Example 2: We'd like to block users with any occurrence of high risk behavior or an overall Fraud Score >= 90
    * 
    * if($result['fraud_score'] >= 90 || $result['transaction_details']['fraudulent_behavior'] === true){
    *		exit(header("Location: https://google.com"));
    * }
    */
    
    /*
    *- Address Verification Example 3: We'd like to block users with an overall Fraud Score >= 90, users with VPN connections, or users with an invalid or abusive physical address
    * 
    * if($result['fraud_score'] >= 90 || $result['vpn'] === true || $result['transaction_details']['valid_billing_address'] === false || $result['transaction_details']['valid_shipping_address'] === false){
    *		exit(header("Location: https://google.com"));
    * }
    */

    /*
    * If you are confused with these examples or simply have a use case
    * not covered here, please feel free to contact IPQualityScore's support
    * team. We'll craft a custom piece of code to meet your requirements.
    */
}

xxxxxxxxxx
 
// Your API Key.
$key = 'YOUR_API_KEY_HERE';
​
/*
* Retrieve the user's IP address. 
* You could also pull this from another source such as a database.
* 
* If you use cloudflare change REMOTE_ADDR to HTTP_CF_CONNECTING_IP
*/
$ip = isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : $_SERVER['HTTP_CLIENT_IP'];
​
​
// Retrieve additional (optional) data points which help us enhance fraud scores.
$user_agent = $_SERVER['HTTP_USER_AGENT']; 
$user_language = $_SERVER['HTTP_ACCEPT_LANGUAGE'];
​
// Set the strictness for this query. (0 (least strict) - 3 (most strict))
$strictness = 0;
​
// You may want to allow public access points like coffee shops, schools, corporations, etc...
$allow_public_access_points = 'true';
​
// Create parameters array.
$parameters = array(
    'user_agent' => $user_agent,
    'user_language' => $user_language,
    'strictness' => $strictness,
    'allow_public_access_points' => $allow_public_access_points
);
​
/* User & Transaction Scoring
* Score additional information from a user, order, or transaction for risk analysis
* All transaction parameters are optional, please remove any that are not used
* Non paid actions such as lead generation and user scoring can be substituted into the "billing" or "shipping" variables
* This feature requires a Premium plan or greater
* Premium users can also adjust transaction scoring rules: https://www.ipqualityscore.com/user/transaction/weights
*/
​
//  All variables are optional - the primary address should be scored in the "billing" variables
    $transaction_parameters = array(
        'billing_address_1' => '',
        'billing_address_2' => '',
        'billing_city' => '',
        'billing_state' => '',
        'billing_zipcode' => '',
        'billing_country' => '',
        'shipping_address_1' => '',
        'shipping_address_2' => '',
        'shipping_city' => '',
        'shipping_state' => '',
        'shipping_zipcode' => '',
        'shipping_country' => ''
);
​
// Format Parameters
if(is_array($transaction_parameters)){
    $formatted_parameters = http_build_query(array_merge($parameters, $transaction_parameters));
} else {
    $formatted_parameters = http_build_query($parameters);
}
​
// Create API URL
$url = sprintf(
    'https://www.ipqualityscore.com/api/json/ip/%s/%s?%s', 
    $key,
    $ip, 
    $formatted_parameters
);
​
// Fetch The Result
$timeout = 5;
​
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, $timeout);
​
$json = curl_exec($curl);
curl_close($curl);
​
// Decode the result into an array.
$result = json_decode($json, true);
​
// Check to see if our query was successful.
if(isset($result['success']) && $result['success'] === true){
    // NOTICE: If you want to use one of the examples below, remove
    // any lines containing /*, */ and *-, then remove * from any of the
    // the remaining lines.
    
    /*
    *- Address Verification Example 1: We'd like to block users with an invalid physical address or address that was recently used for a fraudulent action
    * 
    * if($result['transaction_details']['valid_billing_address'] === false || $result['transaction_details']['valid_shipping_address'] === false){
    *       exit(header("Location: https://google.com"));
    * }
    */
    
    /*
    *- Address Verification Scoring Example 2: We'd like to block users with any occurrence of high risk behavior or an overall Fraud Score >= 90
    * 
    * if($result['fraud_score'] >= 90 || $result['transaction_details']['fraudulent_behavior'] === true){
    *       exit(header("Location: https://google.com"));
    * }
    */
    
    /*
    *- Address Verification Example 3: We'd like to block users with an overall Fraud Score >= 90, users with VPN connections, or users with an invalid or abusive physical address
    * 
    * if($result['fraud_score'] >= 90 || $result['vpn'] === true || $result['transaction_details']['valid_billing_address'] === false || $result['transaction_details']['valid_shipping_address'] === false){
    *       exit(header("Location: https://google.com"));
    * }
    */
​
    /*
    * If you are confused with these examples or simply have a use case
    * not covered here, please feel free to contact IPQualityScore's support
    * team. We'll craft a custom piece of code to meet your requirements.
    */
}

# THIS SHOULD NEVER BE USED IN PRODUCTION AS IS!

# You may need to install Requests pip
# python -m pip install requests

from http.server import BaseHTTPRequestHandler, HTTPServer
import json
import requests

hostName = "localhost"
serverPort = 8080

class IPQS:
    key = "YOUR_API_KEY_HERE"
    def proxy_vpn_api(self, ip: str, vars: dict = {}) -> dict:
        """Method used to lookup Proxy & VPN Detection API 

        Args:
            ip (str): IPv4 or IPV6 to lookup.
            vars (dict, optional): Reffer to https://www.ipqualityscore.com/documentation/proxy-detection-api/address-validation for variables. Defaults to {}.

        Returns:
            dict: Returns json response in an array.
        """
        url = "https://www.ipqualityscore.com/api/json/ip/%s/%s" % (self.key, ip)
        if bool(vars):
            x = requests.get(url, params = vars)
        else:   
            x = requests.get(url)
        return (json.loads(x.text))




class MyServer(BaseHTTPRequestHandler):
    """This is an example basic web server. we limited it to handle "/" path only."""

    def do_GET(self):
        if self.path == "/":
            self.send_response(200)
            self.send_header("Content-type", "text/html")
            self.end_headers()
            self.wfile.write(bytes("<body>", "utf-8"))
            ipqs = IPQS()
            # You pass the the IP Address from self.client_address[0]
            # This example assumes that you have entered a proper API and have sufficient credits.
            print(ipqs.proxy_vpn_api(self.client_address[0])["fraud_score"])
            self.wfile.write(bytes("<p>This is an example do not simply copy paste.</p>", "utf-8"))
            self.wfile.write(bytes("</body></html>", "utf-8"))

if __name__ == "__main__":        
    webServer = HTTPServer((hostName, serverPort), MyServer)
    print("Server started http://%s:%s" % (hostName, serverPort))

    try:
        webServer.serve_forever()
    except KeyboardInterrupt:
        pass

    webServer.server_close()
    print("Server stopped.")

xxxxxxxxxx
 
# THIS SHOULD NEVER BE USED IN PRODUCTION AS IS!
​
# You may need to install Requests pip
# python -m pip install requests
​
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
import requests
​
hostName = "localhost"
serverPort = 8080
​
class IPQS:
    key = "YOUR_API_KEY_HERE"
    def proxy_vpn_api(self, ip: str, vars: dict = {}) -> dict:
        """Method used to lookup Proxy & VPN Detection API 
​
        Args:
            ip (str): IPv4 or IPV6 to lookup.
            vars (dict, optional): Reffer to https://www.ipqualityscore.com/documentation/proxy-detection-api/address-validation for variables. Defaults to {}.
​
        Returns:
            dict: Returns json response in an array.
        """
        url = "https://www.ipqualityscore.com/api/json/ip/%s/%s" % (self.key, ip)
        if bool(vars):
            x = requests.get(url, params = vars)
        else:   
            x = requests.get(url)
        return (json.loads(x.text))
​
​
​
​
class MyServer(BaseHTTPRequestHandler):
    """This is an example basic web server. we limited it to handle "/" path only."""
​
    def do_GET(self):
        if self.path == "/":
            self.send_response(200)
            self.send_header("Content-type", "text/html")
            self.end_headers()
            self.wfile.write(bytes("<body>", "utf-8"))
            ipqs = IPQS()
            # You pass the the IP Address from self.client_address[0]
            # This example assumes that you have entered a proper API and have sufficient credits.
            print(ipqs.proxy_vpn_api(self.client_address[0])["fraud_score"])
            self.wfile.write(bytes("<p>This is an example do not simply copy paste.</p>", "utf-8"))
            self.wfile.write(bytes("</body></html>", "utf-8"))
​
if __name__ == "__main__":        
    webServer = HTTPServer((hostName, serverPort), MyServer)
    print("Server started http://%s:%s" % (hostName, serverPort))
​
    try:
        webServer.serve_forever()
    except KeyboardInterrupt:
        pass
​
    webServer.server_close()
    print("Server stopped.")

Ready to eliminate fraud?

Start fighting fraud now with 5,000 Free Lookups!

We're happy to answer any questions or concerns.

Chat with our fraud detection experts any day of the week.

Call us at: (800) 713-2618

Schedule a Demo Sign Up