Guide Contents
Gettin
Getting Started
Before you can start using POSTman Web Services, you must sign up for a subscription. DMS are happy to provide you with a trial subscription allowing limited usage to get you up and going or to evaluate POSTman Web services if you wish.
To sign up, email info@dmsw.com.au or call 07 3510 9555.
Once your registration is completed, you will be sent a username and password. This username and password is used to both sign-in to the https://postmanws.com site and also to utilize the Web Service itself.
Make sure you keep this username and password secure as any usage attributed to it will be taken from your account.
If you believe your login has been compromised, contact DMS to change your password immediately.
In order to modify your account details, purchase credits or to check on your account’s current usage, go to the https://postmanws.com page and login
The next step is to integrate POSTman Web Services into your website. To do this, first review the interface examples in the Interface Examples section of this document to get a feel as to how you might wish to implement POSTman Web Services. Next review the Reference Manual section to familiarize yourself with POSTman Web Services and its methods. Finally refer to the Program Examples section to see source code examples in C#, Java, PHP and other languages.
POSTman Web Services itself is available from; https://webservice.dmsw.com.au/postman/
To login into the web service, utilize the username and password that DMS has provided.
Finally, it This guide is designed to help you effectively implement POSTman Web Services (PWS).
Table of Contents | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Getting Started
The setup process is as follows:
Purchase PWS credits. Please refer to our FAQ section on how credit use works.
Review your welcome email from our team which includes your username and password
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
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 on the web service website via the PWS Dashboard or via a method call in POSTman Web Services itself. If you believe you are going to run out of usage in the current usage period and do not wish to risk having the service unavailable, then contact DMS immediately via support@dmsw.com.au or by phoning (07) 3510 9555 to top-up your web service usage in the current period or to adjust your subscription.
Integrating POSTman Web Services
Interface Examples
POSTman Web Services can be integrated into virtually any web form or application where an address is captured.
...
If an address cannot be corrected automatically using Australia Post’s AMAS rules, the operator will should be taken to a near matches list such as this one.
...
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 has set a valid username and password by calling this web method.
Input Parameters
Parameter Name | Value | Description |
username | string |
PWS username | |
password | string |
PWS password |
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
Parameter Name | Value | Description |
sessionID | string | Has to set to the string returned by the setLogin function |
mixedCase | boolean | Whether or not the search address can contain |
Mixed cases | ||
expandAbbreviations | boolean | Whether or not Postman engine expands the |
search address’s abbreviations |
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
Parameter Name | Value | Description |
sessionID | string | Has to set to the string returned by the setLogin function |
address1 | string | First line of the address to search for |
address2 | string | Second line of the address to search for |
address3 | string | Third line of the address to search for |
address4 | string | 4th line of the address to search for |
address5 | string | 5th line of the address to search for |
address6 | string | 6th line of the address to search for |
suburb | string | Suburb of the address to search for |
state | string | State of the address to search for |
postcode | string | Postcode of the address to search for |
country | string | Country of the address to search for |
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
Parameter Name | Value | Description |
address1 | string | First line of the address to search for |
address2 | string | Second line of the address to search for |
address3 | string | Third line of the address to search for |
address4 | string | 4th line of the address to search for |
address5 | string | 5th line of the address to search for |
address6 | string | 6th line of the address to search for |
Barcode | string | Barcode of the address to search for |
BSP | string | BSP of the address to search for |
BSPState | string | BSPState of the address to search for |
DPID | string | DPID of the address to search for |
postcode | string | Postcode of the address to search for |
POBoxNo | integer | PoBox number of the address to search for |
POBoxprifix | integer | PoBox perifix of the address to search for |
poBoxsuffix | integer | PoBox suffix of the address to search for |
UnitNo | string | Number of the unit of the address to search for |
unitType | string | Type of the unit of the address to search for |
IsCorrectedAddress | boolean | Whether or not the address is corrected |
IsValidAddress | boolean | Whether or not the address is valid |
IsStreetAddress | boolean | Whether or not the address is an street address |
ScanAddress2
The ScanAddress2 function is the simpler version of ScanAddress, allows mode settings to be passed directly.
Input Parameters
Parameter Name | Value | Description |
sessionID | string | Has to set to the string returned by the setLogin |
function | ||
address1 | string | First line of the address to search for |
address2 | string | Second line of the address to search for |
address3 | string | Third line of the address to search for |
address4 | string | 4th line of the address to search for |
address5 | string | 5th line of the address to search for |
address6 | string | 6th line of the address to search for |
suburb | string | Suburb of the address to search for |
state | string | State of the address to search for |
postcode | string | Postcode of the address to search for |
mixedCase | boolean | Whether or not the search address can contain Mixed cases |
expandAbbreviations | boolean | Whether or not Postman engine expands the search address’s abbreviations |
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.
Parameter Name | Value | Description |
address1 | string | First line of the address to search for |
address2 | string | Second line of the address to search for |
address3 | string | Third line of the address to search for |
address4 | string | 4th line of the address to search for |
address5 | string | 5th line of the address to search for |
address6 | string | 6th line of the address to search for |
Barcode | string | Barcode of the address to search for |
BSP | string | BSP of the address to search for |
BSPState | string | BSPState of the address to search for |
DPID | string | DPID of the address to search for |
postcode | string | Postcode of the address to search for |
POBoxNo | integer | PoBox number of the address to search for |
POBoxprifix | integer | PoBox perifix of the address to search for |
poBoxsuffix | integer | PoBox suffix of the address to search for |
UnitNo | string | Number of the unit of the address to search for |
unitType | string | Type of the unit of the address to search for |
IsCorrectedAddress | boolean | Whether or not the address is corrected |
IsValidAddress | boolean | Whether or not the address is valid |
IsStreetAddress | boolean | Whether or not the address is an street address |
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
Parameter Name | Value | Description |
sessionID | string | Has to set to the string returned by the setLogin function |
maxNumberOfMatches | integer | The maximum number of the returned |
records of |
possible addresses near or similar to the one just scanned |
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
Parameter Name | Value | Description |
address1 | string | First line of the address to search for |
address2 | string | Second line of the address to search for |
address3 | string | Third line of the address to search for |
address4 | string | 4th line of the address to search for |
address5 | string | 5th line of the address to search for |
address6 | string | 6th line of the address to search for |
Barcode | string | Barcode of the address to search for |
BSP | string | BSP of the address to search for |
BSPState | string | BSPState of the address to search for |
DPID | string | DPID of the address to search for |
postcode | string | Postcode of the address to search for |
POBoxNo | integer | PoBox number of the address to search for |
POBoxprifix | integer | PoBox perifix of the address to search for |
poBoxsuffix | integer | PoBox suffix of the address to search for |
UnitNo | string | Number of the unit of the address to search for |
unitType | string | Type of the unit of the address to search for |
IsCorrectedAddress | boolean | Whether or not the address is corrected |
IsValidAddress | boolean | Whether or not the address is valid |
IsStreetAddress | boolean | Whether or not the address is an street address |
CurrentBalance
The CurrentBalance function is the first call made to the Postman KEngine to return the user current balance.
Input Parameters
Parameter Name | Value | Description |
sessionID | string | Has to set to the string returned by the setLogin function |
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 :