# Address by Geocode

## 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](#combined)                   | Lookup addresses using geocode input, which invokes [auNzReverseGeocode ](/loqate-harmony-api/api-specification/deprecated/address-v1.md#aunzreversegeocode)for Australia or New Zealand or [internationalReverseGeocode ](#international)for other countries. |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [internationalReverseGeocode](#international) | Lookup the nearest address or location using geocode input - for all countries including Australia and New Zealand.                                                                                                                                            |

### reverseGeocode <a href="#combined" id="combined"></a>

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

It invokes [auNzReverseGeocode ](/loqate-harmony-api/api-specification/deprecated/address-v1.md#aunzreversegeocode)method for Australia or New Zealand country. For other countries, it invokes [internationalReverseGeocode](#international) method.&#x20;

HTTP `POST` for [internationalReverseGeocode](#international) supports multiple records in the request, while [auNzReverseGeocode ](/loqate-harmony-api/api-specification/deprecated/address-v1.md#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 ](/loqate-harmony-api/api-specification/objects/address-objects.md#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](/loqate-harmony-api/api-specification/objects/address-objects.md#addressrestresponse) object.

{% hint style="success" %}
See [Address Field Mapping Gui](/loqate-harmony-api/guides/best-practices/address-field-mappings.md)[de](/loqate-harmony-api/guides/best-practices/address-field-mappings.md) for integration best practices.
{% endhint %}

#### 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 ](/loqate-harmony-api/api-specification/deprecated/address-v1.md#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](#international) method which will process all records in the request. The `featureOptions` is ignored when invoking [internationalReverseGeocode](#international) 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 <a href="#international" id="international"></a>

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 ](/loqate-harmony-api/api-specification/deprecated/address-v1.md#aunzreversegeocode)method which will return more information.

GET[​/rest​/intl​/reverseGeocode](https://developer.mastersoftgroup.com/harmony/api/method/reverse-geocode.html#/internationalReverseGeocode/reverseGeocodeIntlUsingGET)Lookup the nearest address or location to the given latitude/longitude coordinates - international (AU/NZ and other countries)POST[​/rest​/intl​/reverseGeocode](https://developer.mastersoftgroup.com/harmony/api/method/reverse-geocode.html#/internationalReverseGeocode/reverseGeocodeIntlUsingPOST)Lookup 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](/loqate-harmony-api/api-specification/objects/address-objects.md#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](/loqate-harmony-api/api-specification/objects/address-objects.md#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"
            }
        ]
    }
```

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/address/address-by-geocode.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.