Cloudcheck Loqate API

Overview

The Loqate API services enable a user to look up and validate addresses, emails and phone numbers.

For addresses the user provides a search input and the Loqate API service will search the specified sources of truth (e.g. AUPAF, GNAF, NZPAF or NZAD) and return a detailed address object. By default, the address services support New Zealand and Australia. However it also supports an international lookup service, but the precision of results vary country to country. Please contact our sales team if you would like to access addresses outside of New Zealand and Australia.

The phone validator supports New Zealand and Australian mobile numbers.

The email validator works with any email address.

Address Find

Path	/address/find/	Method	POST

The find method fetches all the addresses that match the search string provided and responds with matching address strings - each with an id which can be used by the Retrieve API.

When requesting an address lookup from the Loqate API, you must include the following parameters as part of the call.

Please note all these parameters must be posted as URL encoded form data. As such, the request should contain a Content-Type header of application/x-www-form-urlencoded.

Parameter	Required	Description
`key`	true	Your API Key.
`signature`	true	An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature.
`nonce`	true	A single-use key generated for this request. Note that each nonce may only be used once for each access key.
`timestamp`	true	The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected.
`data`	true	A JSON string containing the details to be verified.

Request

The address being searched must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.

Example

This is the minimum detail required for finding an address.

{
    "payload": [{
        "fullAddress": "27 Tairua Terrace, Tairua 3508",
        "country": "NZ"
    }],
    "sourceOfTruth": "NZAD"
}

The sourceOfTruth is not required but specifies which source of truth to use. If left blank the default source of truth for your country will be used.

You may also add the featureOptions object to specify filters or other settings to customise your results.

Example

The following request shows an example of provided featureOptions to narrow down the search results and filter out unwanted fields

{
    "featureOptions": {
        "exposeAttributes":1,
        "addressTypeFilter": "urban,rural",
        "positionFilter": "doorstop,rooftop,single",
        "singleLineHitNumber": 10,
        "caseType": "TITLE"
    },
    "payload": [{
        "fullAddress": "27 Tairua Terrace, Tairua 3508",
        "country": "NZ"
    }],
    "sourceOfTruth": "NZAD"
}

All of the options can be found here.

Response

The response will look as follows. Note the id which will need to be provided to the retrieve API to get all of the address details.

Example

{
    "payload": [
        {
            "_type": "AddressIntlV2",
            "fullAddress": "27 TAIRUA TERRACE, TAIRUA 3508",
            "attributes": {
                "Type": "Address"
            },
            "id": "NZ|NZAD|1294275"
        }
    ],
    "messages": [],
    "status": "SUCCESS"
}

Address Retrieve

Path	/address/retrieve/	Method	POST

The find method fetches the address that matches the id provided (which was returned by the find API) and respond with all the known details of that address.

When requesting an address lookup from the Loqate API, you must include the following parameters as part of the call.

Please note all these parameters must be posted as URL encoded form data. As such, the request should contain a Content-Type header of application/x-www-form-urlencoded.

Parameter	Required	Description
`key`	true	Your API Key.
`signature`	true	An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature.
`nonce`	true	A single-use key generated for this request. Note that each nonce may only be used once for each access key.
`timestamp`	true	The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected.
`data`	true	A JSON string containing the details to be verified.

Request

A minimal request will look as follows:

Example

To retrieve addresses based on IDs. The following json will be required.

{
    "payload":[
        {
            "id": "NZ|NZAD|3716883"
        }
    ]
}

Similarly to find, retrieve also has the same optional featureOptions.

Example

{
    "featureOptions": {
        "exposeAttributes":1,
        "caseType": "TITLE"
    },
    "payload":[
        {
            "id": "NZ|NZAD|3716883"
        }
    ]
}

More options are explained in detail here.

Response

The response will look different depending on whether the address is from New Zealand or Australia (and will vary per country for international lookups).

For New Zealand you may expect the response to look as follows:

Example

{
    "payload": [
        {
            "exception": null,
            "country": "New Zealand",
            "eid": null,
            "postalType": "",
            "townCity": "Auckland",
            "subdwelling": "",
            "flatUnitNumber": "",
            "streetName": "Toanga",
            "street": "Toanga Place",
            "street2": null,
            "id": "NZ|NZAD|3716883",
            "streetType": "Place",
            "streetNumber": "27",
            "floorLevelNumber": "",
            "postalNumber": "",
            "deliveredTo": "Y",
            "_type": "ValidatedAddressNz",
            "postcode": "1062",
            "rdNumber": null,
            "lotNumber": "",
            "buildingName": "",
            "flatUnitType": "",
            "floorLevelType": "",
            "fullAddress": "27 Toanga Place, Mount Wellington, Auckland 1062",
            "suburb": "Mount Wellington",
            "streetSuffix": "",
            "attributes": {
                "ParcelId": "7023379",
                "CountryIso2": "NZ",
                "address_type": "Urban",
                "CountryIso3": "NZL",
                "DPID": "3716883",
                "regional_council_id": "2",
                "Latitude": "-36.92748267844001",
                "source": "Council",
                "Longitude": "174.8522563537249",
                "MeshblockId": "635800",
                "address_line3": "Auckland  1062",
                "address_line2": "Mount Wellington",
                "address_line1": "27 Toanga Place",
                "regional_council_name": "Auckland Region",
                "ta_name": "Auckland",
                "XCoordinate": "1764970.93018012",
                "ta_id": "76",
                "YCoordinate": "5911569.74611953"
            },
            "postal": ""
        }
    ],
    "messages": [],
    "status": "SUCCESS"
}

For Australia you may expect the response to look as follows:

Example

{
    "payload": [
        {
            "exception": null,
            "country": "Australia",
            "eid": null,
            "postalType": "",
            "subdwelling": "",
            "flatUnitNumber": "",
            "streetName": "Toallo",
            "street": "Toallo St",
            "street2": null,
            "id": "AU|AUPAF|58220059",
            "state": "NSW",
            "streetType": "St",
            "streetNumber": "27",
            "floorLevelNumber": "",
            "postalNumber": "",
            "_type": "ValidatedAddressAu",
            "postcode": "2549",
            "locality": "Pambula",
            "lotNumber": "",
            "buildingName": "",
            "flatUnitType": "",
            "floorLevelType": "",
            "fullAddress": "27 Toallo St, Pambula NSW 2549",
            "streetSuffix": "",
            "attributes": {
                "CountryIso2": "AU",
                "Barcode": "1301011222020200001230303233202201313",
                "CountryIso3": "AUS",
                "DPID": "58220059",
                "Bsp": "020",
                "PAFPosition": "Rooftop"
            },
            "postal": ""
        }
    ],
    "messages": [],
    "status": "SUCCESS"
}

Phone Validate

Path	/phone/validate/	Method	POST

The Phone Validate API validates up to 100 mobile phone numbers.

Please note all these parameters must be posted as URL encoded form data. As such, the request should contain a Content-Type header of application/x-www-form-urlencoded.

Parameter	Required	Description
`key`	true	Your API Key.
`signature`	true	An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature.
`nonce`	true	A single-use key generated for this request. Note that each nonce may only be used once for each access key.
`timestamp`	true	The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected.
`data`	true	A JSON string containing the details to be verified.

Request

The mobile phone numbers to be validated must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.

Example

{
"phones": [
{
"fullPhoneNumber": "0223456789",
"countryCode": "NZ"
},
{
"fullPhoneNumber": "0412345678",
"countryCode": "AU"
}
],

"consent": "YES"
}

Response

The response JSON contains the details of the validation for each mobile phone.

Example

{
"validationReference": "1ac9d987-4007-4dd9-b5a6-cf547232836c",
"status": "PASS",
"messages": [],
"payload": [
{
"fullPhoneNumber": "0223456789",
"countryCode": "NZ",
"countryPrefix": "64",
"areaCode": 0223456789
"localNumber": "0412345678",
"operatorName": "Spark",
"phoneStatus": "connected|Network confirmed connection",
"exception": ""
},
{
"fullPhoneNumber": "0412345678",
"countryCode": "AU",
"countryPrefix": "61",
"areaCode": "",
"localNumber": "0412345678",
"operatorName": "Vodafone Australia",
"phoneStatus": "connected|Network confirmed connection",
"exception": ""
}
]
}

The possible values of the status field are PENDING, PASS, FAIL and ERROR.

Phone Validation Results

Path	/phone/validate/results/	Method	GET

Returns the results of an earlier phone validation.

Parameter	Required	Description
`key`	true	Your API Key.
`signature`	true	An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature.
`nonce`	true	A single-use key generated for this request. Note that each nonce may only be used once for each access key.
`timestamp`	true	The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected.
`reference`	true	The `validationReference` returned in the initial Phone Validation API response.

Response

See the response notes and example for the Phone Validate endpoint.

Email Validate

Path	/email/validate/	Method	POST

The Email Validate API validates up to 100 email addresses.

Please note all these parameters must be posted as URL encoded form data. As such, the request should contain a Content-Type header of application/x-www-form-urlencoded.

Parameter	Required	Description
`key`	true	Your API Key.
`signature`	true	An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature.
`nonce`	true	A single-use key generated for this request. Note that each nonce may only be used once for each access key.
`timestamp`	true	The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected.
`data`	true	A JSON string containing the details to be verified.

Request

The email addresses to be validated must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.

Example

{
"emails": [
{
"address": "abc@gmail.com"
},
{
"address": "def@ymail.com"
},
{
"address": "xyz@hotmail.com"
}
],

"consent": "YES"
}

Response

The response JSON contains the details of the validation for each email address.

Example

{
"verification": {
"validationReference": "af50ccb0-7732-455b-a102-c4c8077dc2e4",
"status": "PASS",
"payload": [
{
"emailAddress": "abc@gmail.com",
"attributes": {
"domainExists": "VALID",
"mailserverExists": "VALID",
"emailValid": "VALID",
"message": "Email address does not exist on mail server.",
"emailExists": "INVALID"
},
"domainValidated": true,
"mailServerValidated": true,
"mailBoxValidated": false,
"blackListValidated": true,
"formatValidated": true
},
{
"emailAddress": "def@ymail.com",
"attributes": {
"domainExists": "INVALID",
"mailserverExists": "INVALID",
"emailValid": "INVALID",
"message": "Email address is not formatted correctly.",
"emailExists": "INVALID"
},
"domainValidated": false,
"mailServerValidated": false,
"mailBoxValidated": false,
"blackListValidated": true,
"formatValidated": true
},
{
"emailAddress": "xyz@hotmail.com",
"attributes": {
"domainExists": "VALID",
"mailserverExists": "VALID",
"emailValid": "VALID",
"message": "Email verified.",
"emailExists": "VALID"
},
"domainValidated": true,
"mailServerValidated": true,
"mailBoxValidated": true,
"blackListValidated": true,
"formatValidated": true
}
]
}
}

The possible values of the status field are PENDING, PASS, FAIL and ERROR.

Email Validation Results

Path	/email/validate/results/	Method	GET

Returns the results of an earlier email validation.

Parameter	Required	Description
`key`	true	Your API Key.
`signature`	true	An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature.
`nonce`	true	A single-use key generated for this request. Note that each nonce may only be used once for each access key.
`timestamp`	true	The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected.
`reference`	true	The `validationReference` returned in the initial Email Validation API response.

Response

See the response notes and example for the Email Validate endpoint.

featureOptions

Element	Type	Notes
displayGnafLot	"0"\|"1"	Flag which determines if the lot information is displayed in addresses retrieved from GNAF Source of Truth. If the flag is set to "1", the lot information will be returned. Otherwise, the lot information will not be returned. Only applicable for GNAF Source of Truth.
displayTrueLocality	"0"\|"1"	Flag which determines whether to use the true locality or the synonym locality in the lookup result. If the flag is set to "1", the true locality will be returned. Otherwise, the synonym locality will be returned.
positionFilter	Array	[AU ONLY] The positionFilter option has two types of filters: Point filters (when a specific address is retrieved) and Locality filters (where a locality-level address is retrieved). The option values available for Point filters are: POSTAL - filters only postal addresses ROOFTOP - filters only addresses that contain one or more subdwelling addresses (e.g. unit blocks) - the subdwelling addresses are not included DOORSTOP - filters subdwelling addresses within 'ROOFTOP' addresses (e.g. units within a unit block) - the 'ROOFTOP' addresses are not included SINGLE - filters addresses that represent a single address with no subdwellings (e.g. houses) The option values available for Locality filters are: PHYSICAL - filters localities that do not contain any addresses with a 'postal' type POSTAL - filters localities that only contain addresses with a 'postal' type BOTH - filters localities that contain at least one 'postal' address and one 'non-postal' address
addressTypeFilter	Array	[NZ ONLY] The addressTypeFilter option is to filter the result based on the type of delivery point. It is only used for NZPAF and NZAD Source of Truth. The option values available for Address Type filters are: URBAN - filters only Urban Delivery Addresses BOX - filters only PO Box Addresses BAG - filters only Private Bag Addresses RURAL - filters only Rural Delivery Addresses COUNTER - filters only Counter Delivery Addresses - PostShops, etc CMB URBAN - filters only Community MailBox Urban Addresses CMB RURAL - filters only Community MailBox Rural Addresses There is an option to exclude Address Types by using "-" followed by the Address Type value to be excluded. For example `{ "addressTypeFilter": "-urban, -rural" }` to exclude "URBAN" and "RURAL" addresses from the result.
singleLineHitNumber	Integer	The maximum number of results returned from the lookup. Note, modifying this value may impact the performance of the lookup.
exposeAttributes	Integer(0-7)	Flag which determines which attributes to expose for the lookups. "1" (001) - exposes all the default original attributes. "2" (010) - exposes GNAFPlus attributes. "4" (100) - exposes extra AUPAF permission and delivery schedule attributes. The value can be added up for different combinations of attributes exposure. e.g. if it is "3" (001+010=011(3)), it will expose all the default original attributes + GNAFPlus attributes.
exposePhantom	"0"\|"1"	Flag which determines whether to expose phantom addresses for AUPAF address lookup. If the flag is set to "1", it will expose phantom address. Otherwise it will not.
baseSource	"GNAF"\|"AUPAF"	Flag is used in together with SourceOfTruth as AUSOTS. It determines which data source is used as the base for the search result. Additional information from the other source (if available) is added to the addresses from base result. Some addresses may not be found from the base result given the top number but they may be found from the other source. In this case, these addresses are appended to the result list with additional information from the base source (if available).
strictFieldValidation	"0"\|"1"	This option is only effective when the request payload has values for field `state`, `locality`, or `postcode` in addition to `fullAddress`. The default value is "1" which means it strictly limits the results in the response to the requested values for field such as state, locality or postcode. When this option is set to "0", it prioritizes the reseults with requested values in the response but it still includes other search results.
standardizeSource	"AUPAF"\|"GNAF"\|"NZPAF"	The source used to standardize result fields such as Street Type, Flat Unit Type, Floor Level Type, Street Suffix Type and Postal Type.
splitNzFloorLevel	"0"\|"1"	If the flag is set to "1", the floor information will be splitted into "floorLevelType" and "floorLevelNumber". The flag is only available when using with "NZPAF", and will be ignored when using with other sources. The default value is "0".
groupAddresses	"0"\|"1"	A flag to control whether addresses are grouped together or not for "AUPAF" and "GNAF" Source of Truth. If the flag is set to "1", the service will try to collapse sub-dwelling addresses within the same primary address into a group to reduce clutter. The default value is "0".

Cloudcheck Loqate API1.0

Core

APIs

Overview

Address Find

Request

Example

Example

Response

Example

Address Retrieve

Request

Example

Example

Response

Example

Example

Phone Validate

Request

Example

Response

Example

Phone Validation Results

Response

Email Validate

Request

Example

Response

Example

Email Validation Results

Response

featureOptions

Solutions

Industries

About

Contact