Document Viewer

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

Summary

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.

 

Request Information

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.

 

Response Information

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

Specify the GNAF Version to use, such as “202205”.

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.

These errors are rare and in most cases the error can be resolved by retrying the request.

 

If the errors like these happen often please contact Finity to resolve the problem.