Setup Guide - POSTman Web Services

This guide is designed to help technical staff effectively implement POSTman Web Services (PWS).

Getting Started

The setup process is as follows:

1. purchase PWS credits. Please refer to our FAQ section on how credit use works.

2. review your welcome email from our team which includes your username and password

3. visit the PWS Dashboard and use your username and password. We recommend changing your password and checking that your usage credits are displayed correctly on the dashboard

4. work your way through the Integrating POSTman Web Services section

The POSTman Web Services site is where you access the product itself.

It is important that you monitor your usage from time to time; usage can be checked via the PWS Dashboard or via a method call in POSTman Web Services itself.

Integrating POSTman Web Services

Interface Examples

POSTman Web Services can be integrated into virtually any web form or application where an address is captured.

Minor corrections to an address or reformatting of an address to Australia Post standards can be done automatically without a user knowing.

Here you see an address was entered in the web form but was written slightly differently into the underlying database. This happens without the operator knowing it has occurred and improves the consistency of the data in your database.

If an address cannot be corrected automatically using Australia Post’s AMAS rules, the operator will be taken to a near matches list such as this one.

Usually at this point, you provide your operators with three options;

1. Select the correct address from the list

2. Leave the address as it is (a small percentage of valid addresses are not in the PAF, mainly in distant rural communities and new estates)

3. Go back and edit the original address

This type of interface is simple, intuitive and can have a dramatic effect improving the quality of the address data coming from your website.

Reference Manual

Set Log in

The SetLogin function is the first call made to the Postman KEngine to set the username and password. Other web methods are valid only if the user set a valid username and password by calling this web method.

Input Parameters

Return Structure

The call to setLogin will return unique string which needs to be saved by the user for the further use.

SetAddressFormat

The SetAddressFormat function is the first call made to the Postman KEngine to change the way the POSTman formats and returns address data.

Input Parameters

Return Structure

The call to SetAddressFormat will return nothing; it only will set the settings for next search addresses

ScanAddress

The ScanAddress function is the first call made to the Postman KEngine to validate and correct an Australian postal address.

Input Parameters

Return Structure

The call to ScanAddress will return an XML packet with a table in it, POSTmanAddressRecord. The field structure for it is shown below

ScanAddress2

The ScanAddress2 function is the simpler version of ScanAddress, allows mode settings to be passed directly.

Input Parameters

Return Structure

The call to ScanAddress2 will return an XML packet with a table in it, POSTmanAddressRecord. The field structure for it is shown below.

NearestMatches

The NearestMatches function is the first call made to the Postman KEngine to return possible addresses near or similar to the one just scanned.

Input Parameters

Value Description

Return Structure

The call to NearestMatches will return an XML packet with an array of the tables in it, an array of POSTmanAddressRecord. The field structure for each POSTmanAddressRecord is shown below

CurrentBalance

The CurrentBalance function is the first call made to the Postman KEngine to return the user current balance.

Input Parameters

Return Structure

The call to CurrentBalance will return an XML packet with an integer value in it. This integer is your current balance which is decremented by 1 every time you use an address validation.

Program Examples

C#

WebReference.Postman1 pm = new WebReference.Postman1();
string MyID = pm.SetLogin("username", "password");
// set login and get the id
WebReference.POSTmanAddressRecord adr;
adr = pm.ScanAddress(MyID, "1 fake st", "", "", "", "",
"Brisbane", "qld", "6000", "Australia");
// scan address
if(!adr.IsValidAddress)
{
// if the address is not valid
WebReference.POSTmanAddressRecord[] adr2;
adr2 = pm.NearMatches(MyID, 10);
// nearest matches
}
int i = pm.CurrentBalance(MyID);
// check the balance

PHP

The following small example is developed by using PHP 5.2.6
(http://www.php.net/downloads.php) and NuSoap 0.7.3
(http://sourceforge.net/projects/nusoap/);

<html>
<head>
</head>
<body>
<title>Webservice PHP Invocation Testing</title>
<?php
//include NuSoap
require_once('lib/nusoap.php');
echo '<p>Hello DMS WS PHP Invocation Testing</p>';
//Soap call
$client = new
soapclient('http://webservice.dmsw.com.au/postman/postman1.asmx?wsdl', 'wsdl');
//Error handling
$err = $client->getError();
if ($err) {
echo '<h2>Constructor error</h2><pre>' . $err . '</pre>';
}
echo '<p>Retrieve current balance:</p>';
//Stored input parameters in an array
$aryPara = array('myUsername'=>'UserName', 'myPassword'=>'PassWord');
// Call webmethod -- SetLogin of DMS webservice and retrieve a loginGUID
$loginGUID = $client->call('SetLogin',$aryPara);
//Call webmethod - CurrentBalance of DMS webservice
$CurrentBalancearry = array('sessionID'=>($loginGUID['SetLoginResult']));
$aryResult = $client->call('CurrentBalance', $CurrentBalancearry);
//print result
print_r($aryResult);
echo '<p>Address validation testing:</p>';
//stored input parameters in an array NOTICE: sessionID is not 'null' now, the value of
loginGUID should be set to sessionID
$aryAddr = array('sessionID'=> ($loginGUID['SetLoginResult']),'address1'=>' Park
Road ','address2'=> null,'address3'=>
null,'suburb'=>'milton','state'=>'qld','postcode'=>'4030','mixedCase'=>
true,'ExpandAbbreviations'=> true);

//Call webmethod -- ScanAddress2 of DMS webservice
$record = $client->call('ScanAddress2',$aryAddr);

//Error handling
if ($client->fault) {
echo '<h2>Fault</h2><pre>';
print_r($record);
echo '</pre>';
} else {
// Check for errors

$err = $client->getError();
if ($err) {
// Display the error
echo '<h2>Error</h2><pre>' . $err . '</pre>';
} else {
// Display the result
echo 'Result:<br>';
//Print results
while (list($key,$value) = each($record['ScanAddress2Result'])) {
echo "$key : $value<br>";}
echo '</pre>';
}
echo '<p>-----------------</p>';
}
?>
</body>
</html>

If the login details are correct, the result will be similar to this:

Hello WS PHP Invocation Testing

Retrieve current balance:

Array ( [CurrentBalanceResult] => XXXXX ) //XXXXX denotes user's credit

Address validation testing:

Result:
Address1 : Park Road
Address2 :
Address3 :
Address4 :
Address5 :
Address6 :
Suburb : MILTON
State : QLD
PostalCode : 4030
StatusCode : -30
StatusDescription : No matching street address locality
IsStreetAddress : true
IsValidAddress : false
IsCorrectedAddress : false
DPID : 0
BSP :
Barcode :
BSPName :
BSPState :
PrimaryPointFlag : 0
Property1 :
Property2 :
PropertyName :

SortDestination :
LevelNo :
LevelType :
LotNo :
ThoroughfareName : Park
ThoroughfareType :
ThoroughfareTypeSuffix :
UnitNo :
UnitType :
StreetNumber : Lot
ThoroughfareNo1 : 0
ThoroughfareNo1Suffix :
ThoroughfareNo2 : 0
ThoroughfareNo2Suffix :
POBoxNo : 0
POBoxNoPrefix :
POBoxNoSuffix :
POBoxType :
NonAddressData :
CareOfData :
OriginalAddressData : Array
LastError : 0
LastErrorDescription :