Address Validation API Documentation

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 it easy to verify users and validate personal user information.

Address Validation API

Perform Address Verification on any user or transaction with a simple API call. Addresses are verified to ensure the location exists and is valid. Further checks with Fraud Fusion™ perform address reputation scoring to identify data that has been associated with abusive behavior or fraudulent actions.

Scoring Additional User Information

Additional user data such as phone numbers, email addresses, full names, devices, and IP addresses, can also be scored for risk analysis. Please view the Transaction Scoring documentation to learn more.

JSON Address Validation Example API Request

The example below incorporates scoring a physical address with an IP address. It is recommended to pass all billing or shipping variables, or both.

API Lookup with Billing Address Details
The user's primary information should be passed 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)

// 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.")