Overview
finaddress is a Web REST API service built by Finity Consulting Pty Ltd (Finity) to provide address validation and address cleansing services across Australia. It also provide access to our other proprietary products such as finperils, finpoint and Defin’d.
You can access our demonstration site at https://www.finaddress.com.au
Please contact Finity to organise a test token.
GNAF Single Address Validation
High Level Design
Figure 1 shows the high level design of the Address Validation process:
Figure 1 – GNAF Address Validation Process
Address Search API
Summary
Search for addresses that match the search string provided. The service will respond with a list of suggested addresses which can be used to look up further detail in the Address Finder service.
Request Information
HTTP Method: GET
URI: api/AddressSearch/{search string}/
Type |
Name |
Description |
URI Param |
Search string |
The string is required to search. The search string should be URI encoded and then any forward slash (/), and (&) characters should be replaced with underscore (_) |
Header |
token |
A valid token is required to access the service, please contact Finity for more information about getting a token. |
Header |
GNAF_Version |
Specify the GNAF Version to use, such as “202205”. |
Header |
finaddress_memo |
Optional. If this parameter specified then it will be added into the response headers. It will also be recorded in the billing system, as a billing reference. |
Response Information
Success
If the query is successful, a list of Encrypted_GNAF_PIDs and addresses will be returned.
Status: 200
Body: Array<AddressSearchResponse>
Type |
Name |
Description |
URI Param |
Search string |
The string is required to search. The search string should be URI encoded and then any forward slash (/), and (&) characters should be replaced with underscore (_) |
Header |
token |
A valid token is required to access the service, please contact Finity for more information about getting a token. |
Header |
GNAF_Version |
Specify the GNAF Version to use, such as “202205”. |
Header |
finaddress_memo |
Optional. If this parameter specified then it will be added into the response headers. It will also be recorded in the billing system, as a billing reference. |
Failure
Status: 403 or 400
Body: See section “Response Fail Reasons” for a description of the different error messages that can be expected.
Example
Request:
https://www.finaddress.com.au/api/AddressSearch/12_4,%20Bar/
Response:
{ "GNAF_PID": "pF4n5gr013e0gozByLhCQ1=", "Address": "SE 12 40 BLACKALL STREET BARTON ACT 2600 " }, { "GNAF_PID": "pF4n5gr013e0gozByLhCQ8=", "Address": "SE 12 40 BRISBANE AVENUE BARTON ACT 2600 " } ] |
GNAF Address Finder API
The client can retrieve the detail information using a previously retrieved Encrypted_GNAF_PID. Every successful call to the server will be recorded as a chargeable item.
HTTP Method: GET
URI: api/AddressFinderController/{Encrypted_GNAF_PID}/
Type |
Name |
Description |
URI Param |
Encrypted_GNAF_PID |
The Encrypted_GNAF_PID from the response of Address Search API OR GNAF_PID if it is available already. OR The raw address search string, such as “68 HARRINGTON STREET THE ROCKS NSW 2000” |
Header |
token |
A valid token is required to access the service, please contact Finity for more information about getting a token. |
Header |
GNAF_Version |
Specify the GNAF Version to use, such as “202205”. |
Header |
finaddress_memo |
Optional. If this parameter specified then it will be added into the response headers. It will also be recorded in the billing system, as a billing reference. |
Success
If the query is successful, the related products information will be available in the “Elements” field.
Status: 200
Body: AddressFinderResponse
AddressFinderResponse |
||
Field |
Type |
Description |
CustomerKey |
String |
Optional: The key used to identify the customer making the request |
Find_Address |
String |
A unique identifier for the address |
GNAF_PID |
String |
A unique identifier for the address |
GNAF_Address |
String |
A single line string for the address |
ConfidenceScore |
String |
Numeric score indicating the confidence in the accuracy of the result |
Elements |
Array<Datapoint> |
An array of Element records |
Datapoint |
||
Field |
Type |
Description |
Product |
String |
The name of the product the data point relates to |
Field |
String |
The name of the data point |
Value |
String |
The value of the field described by the data point, In cases where the value is null, this field will be represented as "NA". |
Note: To search for specific values, please use a combination of the product and the field. The same field name may be used in different products. New products, such as recently subscribed products, may be included in the API response without prior notice.
Failure
Invalid Encrypted_GNAF_PID
Status: 400
Body:
{ "ContentError":"Bad Encrypted_GNAF_PID" } |
Other Errors
Status: 403 or 400
Body: See section “Response Fail Reasons” for a description of the different error messages that can be expected.
Example
Request:
https://www.finaddress.com.au/Api/AddressFinderController/pF4n5gr013cI8v8CBNhcIYrneHbUogWTOe5ckLVBJOY=/
Response:
{ "CustomerKey": null, "Find_Address": "GAACT714400000", "GNAF_PID": "GAACT714400000", "GNAF_Address": "12 BARKER STREET GRIFFITH ACT 2603 ", "ConfidenceScore": "999", "Elements": [ { "Product": "Base", "Field": "GNAF_Address", "Value": "12 BARKER STREET GRIFFITH ACT 2603 " }, { "Product": "Base", "Field": "SA1_2011", "Value": "80106106403" } ] } |
GNAF Batch Address Cleaning
High Level Design
The batch address cleaning is initiated by sending a request to clean multiple addresses. The service returns a reference to the future response to this request. The caller then polls the status service with the reference to check if the result is ready. Once the response is ready they then call the results service to download the results.
Figure 2 below shows the high level of design in the batch address cleaning process:
Figure 2 – Batch Address Cleaning Process
AddressBatchFinder – Submit Batch
Summary
The client can submit multiple raw addresses and the finaddress server will create a batch cleaning job. The service returns a job reference which should be used to check the status of the job and to download the results.
HTTP Method: POST
URI: api/AddressBatchFinder
Type |
Name |
Description |
Body |
N/A |
A JSON list of strings. The string contains a customer key and a raw address, separated by a pipe (|) character.
The customer key can be used for linking the result back to the origin dataset.
Raw address can be a GNAF_PID, if it is available.
Recommend batch size no more than 10K records. Bigger than 10K batch can be split into smaller batches.
|
Header |
token |
A valid token is required to access the service, please contact Finity for more information about getting a token. |
Header |
GNAF_Version |
|
Header |
Content-Type |
application/json |
Where the request string is constructed as follows: (also see example request below)
String(customer key)|String(address)
Response Information
Success
If the request is successful, then a job reference will be returned and the batch address cleaning is initiate. This reference can be used to query the job status and retrieve all results.
Status: 200
Body: Number
Failure
Status: 403 or 400
Body: See section “Response Fail Reasons” for a description of the different error messages that can be expected.
Example
POST: https://www.finaddress.com.au/Api/AddressBatchFinder
Request Body:
[ "Address 1|68 HARRINGTON STREET THE ROCKS NSW 2000", "Address2|3/3 Collins Street Melbourne 3000", "Address3|91 King William Street Adelaide SA 5000" ] |
Response Body:
123456 |
AddressBatchFinder – Query Batch
Summary
The client uses this service to monitor the status of a job previously submitted by sending the job reference number in with the request.
Request Information
HTTP Method: GET
URI: api/AddressBatchFinder/CheckStatus/{job reference}
Type |
Name |
Description |
URI Param |
Job reference |
The job reference returned by “Submit Batch” API |
Header |
token |
A valid token is required to access the service, please contact Finity for more information about getting a token. |
All the query batch requests should have couple seconds interval between them.
Response Information
Success
If the query is successful one of the following response will be returned. The client should inspect the result to determine whether the results are ready or not.
Response |
Description |
[ "${number1}/${number2} (current speed ${number3} per minute)" ] |
The job is still in progress. · Number1 is the number addresses that were processed most recently. · Number2 is the total number of address yet to process. · Number3 is the number of addresses being processed per minute. |
[“Completed”] |
The job is complete and the client can go ahead and download the results using the “Download Batch Results API” |
Failure
Invalid job reference
Status: 400
Body:
{"ContentError":"Job Id not exist or under a different client"} |
Other Errors
Status: 400 or 403
Body: See section “Response Fail Reasons” for a description of the different error messages that can be expected.
Example
Request:
GET https://www.finaddress.com.au/api/AddressBatchFinder/CheckStatus/123
Response:
[ "125/565 (current speed 30 per minute)" ] |
Job 123 is still in progress. It has completed 125 out of 565 addresses and the rate is 30 per minute |
[ "Completed" ] |
Job 123 is complete |
AddressBatchFinder – Download Batch Results
Summary
The client can get the final results using a job reference of a previously completed job. The results include every address that was submitted in the batch request.
Every successful call to the server will be recorded as a chargeable item.
The results need to be downloaded in 24 hours after the job is created. Otherwise, the results maybe archived and not available any more. In this case, please contact finaddress@finity.com.au .
Request Information
HTTP Method: GET
URI api/AddressBatchFinder/{jobid}
Response Information
Success
If the query is successful, a list results for each address is returned. The structure of each array element is the same as that returned for a single response by the “Address Finder” API.
Status: 200
Body: Array< AddressFinderResponse>
Failure
Status: 400 or 403
Body: See section “Response Fail Reasons” for a description of the different error messages that can be expected.
Example
Request:
GET https://www.finaddress.com.au/api/AddressBatchFinder/123
Response:
[ { "CustomerKey": "776571H", "Find_Address": "68 HARRINGTON STREET THE ROCKS NSW 2000", "GNAF_PID": "GANSW718844175", "GNAF_Address": "68 HARRINGTON STREET THE ROCKS NSW 2000 ", "ConfidenceScore": "999", "Elements": [ { "Product": "Base", "Field": "GNAF_Address", "Value": "68 HARRINGTON STREET THE ROCKS NSW 2000 " } ] }, { "CustomerKey": "1165498H", "Find_Address": "3/3 Collins Street Melbourne 3000", "GNAF_PID": "GAVIC423823607", "GNAF_Address": "1 - 9 COLLINS STREET MELBOURNE VIC 3000 ", "ConfidenceScore": "949", "Elements": [ { "Product": "Base", "Field": "GNAF_Address", "Value": "1 - 9 COLLINS STREET MELBOURNE VIC 3000 " }, { "Product": "Base", "Field": "SA1_2011", "Value": "20604112230" } ] } ] |
PAF Single Address Validation
High Level Design
Figure 3 shows the high level design of the PAF Address Validation process:
Figure 3 – PAF Address Validation Process
PAF Search API
Summary
Search for PAF addresses that match the search string provided. The service will respond with a list of suggested addresses which can be used to look up further detail in the PAF Finder service.
Request Information
HTTP Method: GET
URI: api/PAFSearch/{search string}/
Type |
Name |
Description |
URI Param |
Search string |
The string is required to search. The search string should be URI encoded and then any forward slash (/), and (&) characters should be replaced with underscore (_) |
Header |
token |
A valid token is required to access the service, please contact Finity for more information about getting a token. |
Header |
finaddress_memo |
Optional. If this parameter specified then it will be added into the response headers. It will also be recorded in the billing system, as a billing reference. |
Response Information
Success
If the query is successful, a list of Encrypted_DPIDs and addresses will be returned.
Status: 200
Body: Array<PAFSearchResponse>
PAFSearchResponse |
||
Field |
Type |
Description |
DPID |
String |
The Encrypted_DPID to use when looking up the address details using PAF Finder |
Address |
String |
The address string that is a potential match for the search string |
State |
String |
The state of the address |
Failure
Status: 403 or 400
Body: See section “Response Fail Reasons” for a description of the different error messages that can be expected.
Example
Request:
https://www.finaddress.com.au/api/PAFSearch/3%20james%20street%20bo/
Response:
[ { "DPID": "wqBTszfcimA20GAirKe4g5Cfry(10043)5Do6B", "Address": "3 JAMES ST BOLWARRA HEIGHTS NSW 2320", "State": "NSW" }, { "DPID": "22Jx3lqkdkmJzpgL1TbHxkOq6DgqJ8Go", "Address": "3 JAMES ST BOONAH QLD 4310", "State": "QLD" }, { "DPID": "Ue3tCiVcCqGQMGFs62MQ(10047)zZDBb0BFdHH", "Address": "3 JAMES ST MOUNT MORGAN QLD 4714", "State": "QLD" } ] |
PAF Finder API
Summary
The client can retrieve the PAF detailed information using a previously retrieved Encrypted_DPID. Every successful call to the server will be recorded as a chargeable item.
Request Information
HTTP Method: GET
URI: api/PAFFinder/{Encrypted_DPID}/
Type |
Name |
Description |
URI Param |
Encrypted_DPID |
The Encrypted_DPID from the response of PAF Search API OR DPID if it is available already. |
Header |
token |
A valid token is required to access the service, please contact Finity for more information about getting a token. |
Header |
finaddress_memo |
Optional. If this parameter specified then it will be added into the response headers. It will also be recorded in the billing system, as a billing reference. |
Response Information
Success
If the query is successful, the related products information will be available in the “Elements” field.
Status: 200
Body: PAFFinderResponse
PAFFinderResponse |
||
Field |
Type |
Description |
CustomerKey |
String |
Optional: The key used to identify the customer making the request |
Find_Address |
String |
A unique identifier for the address |
DPID |
String |
A unique identifier for the address |
PAF_Address |
String |
A single line string for the address |
Elements |
Array<Datapoint> |
An array of Element records |
Datapoint |
||
Field |
Type |
Description |
Product |
String |
The name of the product the data point relates to |
Field |
String |
The name of the data point |
Value |
String |
The value of the field described by the data point |
Failure
Invalid Encrypted_DPID
Status: 400
Body:
{ "ContentError":"Bad Encrypted_DPID" } |
Other Errors
Status: 403 or 400
Body: See section “Response Fail Reasons” for a description of the different error messages that can be expected.
Example
Request:
https://www.finaddress.com.au/Api/PAFFinder/22Jx3lqkdkmJzpgL1TbHxkOq6DgqJ8Go/
Response:
{ "CustomerKey": null, "Find_Address": "34625516", "DPID": "34625516", "PAF_Address": "3 JAMES ST BOONAH QLD 4310", "Elements": [ { "Product": "PAFBase", "Field": "DPID", "Value": "34625516" },
{ "Product": "PAFBase", "Field": "STREET_NAME", "Value": "JAMES" }, { "Product": "PAFBase", "Field": "STREET_TYPE", "Value": "ST" }, { "Product": "PAFBase", "Field": "LOCALITY_NAME", "Value": "BOONAH" }, { "Product": "PAFBase", "Field": "POSTCODE", "Value": "4310" }, { "Product": "PAFBase", "Field": "STATE", "Value": "QLD" }, { "Product": "PAFBase", "Field": "PRIMARY_POINT_IND", "Value": "R" }, { "Product": "PAFBase", "Field": "PAF_VERSION", "Value": "2021-4" } ] } |
PAF Suburb Finder API
Summary
Search for PAF suburbs that match the search string
provided. The service will respond with a list of suggested suburbs with
detailed information. Calls to this API will use allowance.
Request Information
HTTP Method: GET
URI: api/PAFSuburbFinder/{Search string }/
Type |
Name |
Description |
URI Param |
Search string |
The
string is required to search. It can be a postcode. The search string should
be URI encoded and then any forward slash (/), and (&) characters should
be replaced with an underscore (_) |
Header |
token |
A valid token is required to
access the service, please contact Finity for more information about getting
a token. |
Header |
finaddress_memo |
Optional. If this parameter specified
then it will be added into the response headers. It will also be recorded in
the billing system, as a billing reference. |
Response Information
Success
If the query is
successful, a list of suburb information will be returned.
Status: 200
Body: List of PAFSubrb
PAFSubrb |
||
Field |
Type |
Description |
Postcode |
String |
Postcode |
Locality |
String |
Locality, known as Suburb. |
State |
String |
State |
Category |
String |
Post Office Category, such as
“Delivery Area”, “Post Office Boxes” |
Comment |
String |
Comment to the Locality/Suburb |
Failure
Other Errors
Status: 403 or 400
Body: See section “Response Fail
Reasons” for a description of the different error
messages that can be expected.
Example
Request:
https://www.finaddress.com.au/Api/PAFSuburbFinder/richlands/
Response:
[ { "Postcode":
"2580", "Locality":
"RICHLANDS", "State":
"NSW", "Category":
"Delivery Area", "Comment":
"" }, { "Postcode":
"4077", "Locality":
"RICHLANDS", "State":
"QLD", "Category":
"Delivery Area", "Comment":
"" } ] |
A. Response Fail Reasons
If there is an error either as a result of invalid input or some server condition then one of the following messages will be included in the response body.
The JSON object returned will contain one of the following keys and a description to explain what caused the error condition:
· AuthError
· AllowanceError
· InternalServerError
· ContentError
The client should inspect every response and check whether any of the above keys exist and if they do treat the response as an error.
Example error responses
Status |
Response |
Reason |
403 |
{"AuthError":"Token does not Exist"} |
The token request header is not present |
|
{"AuthError":"Invalid Token"}
|
A token was found in the request header, but it was invalid.
A token is invalid if: · It has expired · Domain which the request originated from does not match the domain the token was created for |
403 |
{"AuthError":"Authentication Denied"}
|
A token was found in the request header, but it was unable to pass the Authentication.
Authentication will fail when: · Performing action on a wrong ID, such as accessing some other clients’ batch converting results. · Performing action which the token is not allowed to, such as ReverseGeo
|
403 |
{ "AllowanceError":"exceed monthly allowance for the token fin_perils" } |
The request exceeded the monthly allowance on one of the products included in the request.
Please contact Finity to increase the monthly allowance.
|
400 |
{"ContentError":"Missing GNAF-Version in request head"} |
When a request header is missing. |
400 |
{"ContentError":"Format is not correct"} |
When a request with unexpected format in its contents, system will return this message. |
500 |
{ "InternalServerError":"Unexpected Error, please try again later." } |
An unexpected error occurred. The error was logged and
this message is returned to the client.
If the errors like these happen often please contact Finity to resolve the problem. |