(Perl) UPS Address Validation (City, State, Zip)

Demonstrates making a call to the UPS address validation REST API.

Chilkat Perl Downloads Perl Module for Windows, MacOS, Linux, Alpine Linux, Solaris

use chilkat();

# This example requires the Chilkat API to have been previously unlocked.
# See Global Unlock Sample for sample code.

$http = chilkat::CkHttp->new();

$url = "https://wwwcie.ups.com/rest/AV";

# Send an HTTP request with the following JSON body:

# {
#   "AccessRequest": {
#     "AccessLicenseNumber": "Your Access License Number",
#     "UserId": "Your Username",
#     "Password": "Your Password"
#   },
#   "AddressValidationRequest": {
#     "Request": {
#       "TransactionReference": {
#         "CustomerContext": "Your Customer Context"
#       },
#       "RequestAction": "AV"
#     },
#     "Address": {
#       "City": "ALPHARETTA",
#       "StateProvinceCode": "GA",
#       "PostalCode": "30005"
#     }
#   }
# }

# Build the above JSON.
$json = chilkat::CkJsonObject->new();
$json->UpdateString("AccessRequest.AccessLicenseNumber","UPS_ACCESS_KEY");
$json->UpdateString("AccessRequest.UserId","UPS_USERNAME");
$json->UpdateString("AccessRequest.Password","UPS_PASSWORD");
$json->UpdateString("AddressValidationRequest.Request.TransactionReference.CustomerContext","Your Customer Context");
$json->UpdateString("AddressValidationRequest.Request.RequestAction","AV");
$json->UpdateString("AddressValidationRequest.Address.City","ALPHARETTA");
# We're making an intentional mistake here by passing CA instead of GA.
$json->UpdateString("AddressValidationRequest.Address.StateProvinceCode","CA");
$json->UpdateString("AddressValidationRequest.Address.PostalCode","30005");

$sb = chilkat::CkStringBuilder->new();
# resp is a HttpResponse
$resp = $http->PostJson3($url,"application/json",$json);
if ($http->get_LastMethodSuccess() != 1) {
    print $http->lastErrorText() . "\r\n";
    exit;
}

print "status = " . $resp->get_StatusCode() . "\r\n";

# A 200 response status indicate success.
if ($resp->get_StatusCode() != 200) {
    print $resp->bodyStr() . "\r\n";
    print "Failed." . "\r\n";

    exit;
}

$json->Load($resp->bodyStr());
$json->put_EmitCompact(0);
print $json->emit() . "\r\n";

# A successful exact response looks like this:

# {
#   "AddressValidationResponse": {
#     "Response": {
#       "TransactionReference": {
#         "CustomerContext": "Your Customer Context"
#       },
#       "ResponseStatusCode": "1",
#       "ResponseStatusDescription": "Success"
#     },
#     "AddressValidationResult": {
#       "Rank": "1",
#       "Quality": "1.0",
#       "Address": {
#         "City": "ALPHARETTA",
#         "StateProvinceCode": "GA"
#       },
#       "PostalCodeLowEnd": "30005",
#       "PostalCodeHighEnd": "30005"
#     }
#   }
# }
# 

# A successful response that was not an exact match provides an array of closest matches, like this:

# {
#   "AddressValidationResponse": {
#     "Response": {
#       "TransactionReference": {
#         "CustomerContext": "Your Customer Context"
#         "Quality": "0.9875",
#         "Address": {
#       },
#       "ResponseStatusCode": "1",
#       "ResponseStatusDescription": "Success"
#     },
#     "AddressValidationResult": [
#       {
#         "Rank": "1",
#           "City": "ALPHARETTA",
#           "StateProvinceCode": "GA"
#         },
#         "PostalCodeLowEnd": "30005",
#         "PostalCodeHighEnd": "30005"
#       },
#       {
#         "Rank": "2",
#         "Quality": "0.9750",
#         "Address": {
#           "City": "ALPHARETTA",
#           "StateProvinceCode": "GA"
#         },
#         "PostalCodeLowEnd": "30004",
#         "PostalCodeHighEnd": "30004"
#       },
#       {
#         "Rank": "3",
#         "Quality": "0.9750",
#         "Address": {
#           "City": "ALPHARETTA",
#           "StateProvinceCode": "GA"
#         },
#         "PostalCodeLowEnd": "30009",
#         "PostalCodeHighEnd": "30009"
#       }
#     ]
#   }
# }

# Use the online tool at Generate JSON Parsing Code
# to generate JSON parsing code.

$numResults = $json->SizeOfArray("AddressValidationResponse.AddressValidationResult");
if ($numResults < 0) {

    # Here's parse code for the above JSON exact response:
    $customerContext = $json->stringOf("AddressValidationResponse.Response.TransactionReference.CustomerContext");
    $statusCode = $json->stringOf("AddressValidationResponse.Response.ResponseStatusCode");
    $statusDescription = $json->stringOf("AddressValidationResponse.Response.ResponseStatusDescription");
    $resultRank = $json->stringOf("AddressValidationResponse.AddressValidationResult.Rank");
    $resultQuality = $json->stringOf("AddressValidationResponse.AddressValidationResult.Quality");
    $city = $json->stringOf("AddressValidationResponse.AddressValidationResult.Address.City");
    $provinceCode = $json->stringOf("AddressValidationResponse.AddressValidationResult.Address.StateProvinceCode");
    $postalCodeLowEnd = $json->stringOf("AddressValidationResponse.AddressValidationResult.PostalCodeLowEnd");
    $postalCodeHighEnd = $json->stringOf("AddressValidationResponse.AddressValidationResult.PostalCodeHighEnd");

    print "Exact match!" . "\r\n";
    print "postal code: " . $postalCodeLowEnd . "\r\n";

}
else {

    print "Non-Exact match." . "\r\n";

    $customerContext = $json->stringOf("AddressValidationResponse.Response.TransactionReference.CustomerContext");
    $statusCode = $json->stringOf("AddressValidationResponse.Response.ResponseStatusCode");
    $statusDescription = $json->stringOf("AddressValidationResponse.Response.ResponseStatusDescription");
    $i = 0;
    while ($i < $numResults) {
        $json->put_I($i);
        $rank = $json->stringOf("AddressValidationResponse.AddressValidationResult[i].Rank");
        print "rank: " . $rank . "\r\n";
        $quality = $json->stringOf("AddressValidationResponse.AddressValidationResult[i].Quality");
        $addressCity = $json->stringOf("AddressValidationResponse.AddressValidationResult[i].Address.City");
        print "addressCity: " . $addressCity . "\r\n";
        $addressStateProvinceCode = $json->stringOf("AddressValidationResponse.AddressValidationResult[i].Address.StateProvinceCode");
        $postalCodeLowEnd = $json->stringOf("AddressValidationResponse.AddressValidationResult[i].PostalCodeLowEnd");
        print "postal code: " . $postalCodeLowEnd . "\r\n";
        $postalCodeHighEnd = $json->stringOf("AddressValidationResponse.AddressValidationResult[i].PostalCodeHighEnd");
        $i = $i + 1;
    }

}