Address by Geocode

Reverse geocode or Address by Geocode methods take a pair of latitude and longitude coordinates as an input and return addresses information that match the search parameters.

Reverse geocode methods

Reverse geocode methods take a pair of latitude and longitude coordinates as an input and return addresses information that match the search parameters.

reverseGeocode

Lookup addresses using geocode input, which invokes auNzReverseGeocode for Australia or New Zealand or internationalReverseGeocode for other countries.

internationalReverseGeocode

Lookup the nearest address or location using geocode input - for all countries including Australia and New Zealand.

reverseGeocode

Lookup addresses using the geocode input, invoking different method based on the identified country of the first geocode input.

It invokes auNzReverseGeocode method for Australia or New Zealand country. For other countries, it invokes internationalReverseGeocode method.

HTTP POST for internationalReverseGeocode supports multiple records in the request, while auNzReverseGeocode will only process the first record in the request.

Resource URL

    GET/POST    https://hosted.mastersoftgroup.com/harmony/rest/reverseGeocode

Request

The request body is an AddressRestRequest object:

  • The attributes with latitude and longitude is required

  • The sourceOfTruth is optional - for Australia and New Zealand only. The supported Source of Truths are GNAF, NZPAF, NZAD, CNAR (default is GNAF for Australia and NZPAF for New Zealand).

  • The featureOptions is optional - for Australia and New Zealand only. The supported feature options are displayGnafLot, singleLineHitNumber (default 20), caseType, exposeAttributes, radius (default 50 for 50 meters radius).

Response

The response body is an AddressRestResponse object.

See Address Field Mapping Guide for integration best practices.

Examples

Request 1: the first record in below request is an Australian geocode, the second record is a New Zealand geocode, and the rest are not Australia nor New Zealand geocodes.

    {
        "payload": [
            { "attributes": { "latitude": "-16.82082713", "longitude": "145.63726544" }},
            { "attributes": { "latitude": "-36.89131346840618", "longitude": "174.61055106781905" }},
            { "attributes": { "latitude": "57.1536", "longitude": "-2.3003" }},
            { "attributes": { "latitude": "45.69312", "longitude": "-73.92453" }}
        ],
        "featureOptions": { "singleLineHitNumber": "2", "caseType": "UPPER","radius":"50" }
    }

Response of Request 1: as the first record is identified as Australia country, it invokes auNzReverseGeocode method which will only process the first record. There are 2 addresses found within 50 meters radius of the first geocode input.

{
	"status": "SUCCESS",
	"messages": [],
	"payload": [
		{
			"_type": "AddressAu",
			"fullAddress": "LOT 810 1 MEEROO STREET, KURANDA QLD 4881",
			"country": null,
			"postcode": "4881",
			"street2": null,
			"street": "MEEROO STREET",
			"streetNumber": "1",
			"postal": "",
			"postalType": "",
			"postalNumber": "",
			"buildingName": "",
			"subdwelling": "LOT 810",
			"eid": "52F76415F832A4B586F7811CD67E54750D064606E46C4D8414C86833B2D59CD0",
			"lotNumber": "810",
			"flatUnitNumber": "",
			"flatUnitType": "",
			"floorLevelNumber": "",
			"floorLevelType": "",
			"streetSuffix": "",
			"streetType": "STREET",
			"streetName": "MEEROO",
			"attributes": null,
			"id": null,
			"state": "QLD",
			"locality": "KURANDA"
		},
		{
			"_type": "AddressAu",
			"fullAddress": "LOT 809 3 MEEROO STREET, KURANDA QLD 4881",
			"country": null,
			"postcode": "4881",
			"street2": null,
			"street": "MEEROO STREET",
			"streetNumber": "3",
			"postal": "",
			"postalType": "",
			"postalNumber": "",
			"buildingName": "",
			"subdwelling": "LOT 809",
			"eid": "26384A508C51D25CC97B59B8405AF029420BFD597482AFE79D075E31CEB08661",
			"lotNumber": "809",
			"flatUnitNumber": "",
			"flatUnitType": "",
			"floorLevelNumber": "",
			"floorLevelType": "",
			"streetSuffix": "",
			"streetType": "STREET",
			"streetName": "MEEROO",
			"attributes": null,
			"id": null,
			"state": "QLD",
			"locality": "KURANDA"
		}
	]
}

Request 2: the first record in below request is not an Australian nor New Zealand geocode.

    {
        "payload": [
            { "attributes": { "latitude": "57.1536", "longitude": "-2.3003" }},
            { "attributes": { "latitude": "45.69312", "longitude": "-73.92453" }},
            { "attributes": { "latitude": "-16.82082713", "longitude": "145.63726544" }},
            { "attributes": { "latitude": "-36.89131346840618", "longitude": "174.61055106781905" }},
        ],
        "featureOptions": { "singleLineHitNumber": "2", "caseType": "UPPER","radius":"50" }
    }

Response of Request 2: it invokes internationalReverseGeocode method which will process all records in the request. The featureOptions is ignored when invoking internationalReverseGeocode method.

    {
        "status": "SUCCESS",
        "messages": [],
        "payload": [
            {
                "_type": "AddressIntl",
                "fullAddress": null,
                "country": "GB",
                "postcode": "AB32",
                "street2": null,
                "street": "Westdyke Terrace",
                "streetNumber": "9",
                "postal": null,
                "postalType": null,
                "postalNumber": null,
                "buildingName": null,
                "subdwelling": null,
                "attributes": {
                    "Latitude": "57.153645",
                    "Longitude": "-2.300365",
                    "Distance": "0.0"
                },
                "id": null,
                "district": null,
                "city": "Westhill",
                "province": "SCT"
            },
            {
                "_type": "AddressIntl",
                "fullAddress": null,
                "country": "CA",
                "postcode": "J7J",
                "street2": null,
                "street": "Rue Brault",
                "streetNumber": "12770",
                "postal": null,
                "postalType": null,
                "postalNumber": null,
                "buildingName": null,
                "subdwelling": null,
                "attributes": {
                    "Latitude": "45.693214",
                    "Longitude": "-73.9244",
                    "Distance": "0.0"
                },
                "id": null,
                "district": null,
                "city": "Mirabel",
                "province": "QC"
            },
            {
                "_type": "AddressIntl",
                "fullAddress": null,
                "country": "AU",
                "postcode": "4881",
                "street2": null,
                "street": "Thongon Street",
                "streetNumber": "19",
                "postal": null,
                "postalType": null,
                "postalNumber": null,
                "buildingName": null,
                "subdwelling": null,
                "attributes": {
                    "Latitude": "-16.820555",
                    "Longitude": "145.636826",
                    "Distance": "0.0"
                },
                "id": null,
                "district": null,
                "city": "Cairns",
                "province": "Queensland"
            },
            {
                "_type": "AddressIntl",
                "fullAddress": null,
                "country": "NZ",
                "postcode": "0612",
                "street2": null,
                "street": "San Valentino Drive",
                "streetNumber": "61",
                "postal": null,
                "postalType": null,
                "postalNumber": null,
                "buildingName": null,
                "subdwelling": null,
                "attributes": {
                    "Latitude": "-36.891792",
                    "Longitude": "174.611069",
                    "Distance": "0.0"
                },
                "id": null,
                "district": null,
                "city": "Auckland",
                "province": "North Island"
            }
        ]
    }

internationalReverseGeocode

Lookup the nearest address or location using the WGS84 geocode input. It also returns attributes for WGS84 Latitude and Longitude coordinates of the location and the Distance in KM from the CentrePoint to this address.

It supports all countries including Australia and New Zealand. HTTP POST supports multiple records in the request.

Note: for reverse geocoding Australia and New Zealand addresses, you can use auNzReverseGeocode method which will return more information.

GET​/rest​/intl​/reverseGeocodeLookup the nearest address or location to the given latitude/longitude coordinates - international (AU/NZ and other countries)POST​/rest​/intl​/reverseGeocodeLookup the nearest address or location to the given latitude/longitude coordinates - international (AU/NZ and other countries)

Resource URL

    GET/POST    https://hosted.mastersoftgroup.com/harmony/rest/intl/reverseGeocode

Request

The request body is an AddressRestRequest object:

  • The attributes with WGS84 latitude and longitude is required

    {
        "payload": [
            { "attributes": { "latitude": "-33.86440996", "longitude": "151.20828704" } },
            { "attributes": { "latitude": "57.1536", "longitude": "-2.3003" } }
        ]
    }

Response

The response body is an AddressRestResponse object:

    {
        "status": "SUCCESS",
        "messages": [],
        "payload": [
            {
                "_type": "AddressIntl",
                "fullAddress": null,
                "country": "AU",
                "postcode": "2000",
                "street2": null,
                "street": "Abercrombie Lane",
                "streetNumber": "1",
                "postal": null,
                "postalType": null,
                "postalNumber": null,
                "buildingName": null,
                "subdwelling": null,
                "attributes": {
                    "Latitude": "-33.864185",
                    "Longitude": "151.208145",
                    "Distance": "0.0"
                },
                "id": null,
                "district": null,
                "city": "Sydney",
                "province": "New South Wales"
            },
            {
                "_type": "AddressIntl",
                "fullAddress": null,
                "country": "GB",
                "postcode": "AB32",
                "street2": null,
                "street": "Westdyke Terrace",
                "streetNumber": "9",
                "postal": null,
                "postalType": null,
                "postalNumber": null,
                "buildingName": null,
                "subdwelling": null,
                "attributes": {
                    "Latitude": "57.153645",
                    "Longitude": "-2.300365",
                    "Distance": "0.0"
                },
                "id": null,
                "district": null,
                "city": "Westhill",
                "province": "SCT"
            }
        ]
    }

PreviousAddress Validation & LookupNextAddress Cleanse

Last updated