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": ""

}

]

Part III Appendices

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.

Overview

finaddress is a Web REST API service built by Finity Consulting Pty Ltd (Finity) to provide address validation and address cleansing services across New Zealand. It also provide access to our other proprietary products such as finperils.

You can access our demonstration site at https://www.finaddress.com.au/home/nz

Please contact Finity to organise a test token.

FNAF Single Address Validation

High Level Design

Figure 1 shows the high level design of the Address Validation process:

Figure 1 – FNAF Address Validation Process

FNAF 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 FNAF Address Finder service.

Request Information

HTTP Method: GET

URI: api/NZAddressSearch/{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	NZ_Version	Specify the FNAF Version to use, such as “202209”.
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_NZ_IDs and addresses will be returned.

Status: 200

Body: Array<NZAddressSearchResponse>

NZAddressSearchResponse
Field	Type	Description
NZ_ID	String	The Encrypted_NZ_ID to use when looking up the address details using Address Finder
Address	String	The address string that is a potential match for the search string

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/NZAddressSearch/12_4,%20Bar/

Response:

[

{

"NZ_ID": "AC1DcF3gOwoVleH10043H1ar9P1BDMM1yIXg",

"Address": "FLAT 12 4 BAFFLES CRESCENT SILVERDALE HAMILTON 3216"

{

"NZ_ID": "AC1DcF3gOwo6TTD2M825qEaZ310043510043abn10047",

"Address": "FLAT 12 4A BAFFLES CRESCENT SILVERDALE HAMILTON 3216"

}

]

FNAF Address Finder API

Summary

The client can retrieve the detail information using a previously retrieved Encrypted_NZ_ID. Every successful call to the server will be recorded as a chargeable item.

Request Information

HTTP Method: GET
URI: api/NZAddressFinderController/{Encrypted_NZ_ID}/

Type	Name	Description
URI Param	Encrypted_NZ_ID	The Encrypted_NZ_ID from the response of FNAF Address Search API OR NZ_ID if it is available already. OR The raw address search string, such as “79 Queen Street Auckland 1010”
Header	token	A valid token is required to access the service, please contact Finity for more information about getting a token.
Header	NZ_Version	Specify the FNAF Version to use, such as “202209”.
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: NZAddressFinderResponse

NZAddressFinderResponse
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
NZ_ID	String	A unique identifier for the address
NZ_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".

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/NZAddressFinderController/AC1DcF3gOwoVleH10043H1ar9P1BDMM1yIXg/

Response:

{

"CustomerKey": null,

"Find_Address": "NZP1232834",

"NZ_ID": "NZP1232834",

"NZ_Address": "FLAT 12 4 BAFFLES CRESCENT SILVERDALE HAMILTON 3216",

"ConfidenceScore": "999",

"Elements": [

{

"Product": "Base",

"Field": "NZ_Address",

"Value": "FLAT 12 4 BAFFLES CRESCENT SILVERDALE HAMILTON 3216"

{

"Product": "Base",

"Field": "STATNZ_MB_2020",

"Value": "0884900"

}

]

}

FNAF Batch Address Cleaning

High Level Design

Figure 2 below shows the high level of design in the batch address cleaning process:

Figure 2 – FNAF Batch Address Cleaning Process

FNAF AddressBatchFinder – Submit Batch

Summary

HTTP Method: POST

URI: api/NZBatchFinder

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 NZ_ID, 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	NZ_Version	Specify the FNAF Version to use, such as “202209”.
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/NZBatchFinder

Request Body:

[

"Address1|79 Queen Street Auckland 1010",

"Address2|79 Queen Street Northcode Point Auckland 0627 ",

"Address3|99 Queen Street Auckland 1010"

]

Response Body:

123456

FNAF 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/NZBatchFinder/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/NZBatchFinder/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

FNAF 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/NZBatchFinder/{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 “FNAF Address Finder” API.

Status: 200

Body: Array< NZAddressFinderResponse>

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/NZAddressBatchFinder/123

Response:

[

{

"CustomerKey": "Address1",

"Find_Address": "79 Queen Street Auckland 1010",

"NZ_ID": "NZS1132351",

"NZ_Address": "79 - 85 QUEEN STREET AUCKLAND CENTRAL AUCKLAND 1010 ",

"ConfidenceScore": "999",

"Elements": [

{

"Product": "Base",

"Field": "NZ_Address",

"Value": "79 - 85 QUEEN STREET AUCKLAND CENTRAL AUCKLAND 1010"

}

]

{

"CustomerKey": "Address2",

"Find_Address": "99 Queen Street Northcode Point Auckland 0627 ",

"NZ_ID": "NZP853009",

"NZ_Address": "99 QUEEN STREET NORTHCOTE POINT AUCKLAND 0627 ",

"ConfidenceScore": "999",

"Elements": [

{

"Product": "Base",

"Field": "NZ_Address",

"Value": "99 QUEEN STREET NORTHCOTE POINT AUCKLAND 0627 "

{

"Product": "Base",

"Field": "STATNZ_MB_2020",

"Value": "0358700"

}

]

}

]

Part III Appendices

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 NZ_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.

API Documentation

A. Response Fail Reasons

A. Response Fail Reasons