# Address International

{% hint style="danger" %}
These methods have been deprecated. 

We recommend you upgrade your service to the latest [Address Validation method](https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/address/address-validation-and-lookup). Upgrade at no cost and improved performance.
{% endhint %}

## International address lookup methods

International address lookup methods take complete or partial address information as an input and perform a search against a given country **other than Australia or New Zealand,** returning address information that matches the search parameters.

| [find](#address)          | Lookup international addresses using a single-line input address.                          |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| [retrieve](#buildingname) | Retrieve international address details using the result from international address lookup. |

### find <a href="#address" id="address"></a>

Lookup international addresses from a given country other than Australia/New Zealand using a single-line input address.

#### Resource URL

```
    POST    https://hosted.mastersoftgroup.com/harmony/rest/intl/address/find
    
```

#### Or if using GET

```
    GET    https://hosted.mastersoftgroup.com/harmony/rest/intl/address/find
    
```

#### Request (POST)

The request body is an [AddressRestRequest ](https://docs.mastersoftgroup.com/loqate-harmony-api/objects/address-objects#addressrestrequest)object:

* The `fullAddress` attribute is required
* The `country` attribute is required,  its value should be an [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

```json
     {
        "payload": [ { "fullAddress": "10 Downing Street", "country": "GB" } ]
    }
 
```

#### Request Parameters (GET)

* The `fullAddress` parameter is required
* The `country`parameter is required,   its value should be an [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

#### Response

The response body is an [AddressRestResponse](https://docs.mastersoftgroup.com/loqate-harmony-api/objects/address-objects#addressrestresponse) object:

```json
       {
        "status": "SUCCESS",
        "messages": [],
        "payload": [
            {
                "fullAddress": "10 Downing Street SomeCity, B63 3TA",
                "country": null,
                "postcode": null,
                "street2": null,
                "street": null,
                "streetNumber": null,
                "postal": null,
                "postalType": null,
                "postalNumber": null,
                "buildingName": null,
                "subdwelling": null,
                "attributes": null,
                "id": "GB|RM|A|123456",
                "district": null,
                "city": null,
                "province": null
            }
        ]
    }
```

### retrieve <a href="#buildingname" id="buildingname"></a>

Retrieve international address details using the address `id` returned from the international address lookup.

#### Resource URL

```
    POST    https://hosted.mastersoftgroup.com/harmony/rest/intl/address/retrieve    
```

#### Or if using GET

```
    GET    https://hosted.mastersoftgroup.com/harmony/rest/intl/address/retrieve
```

#### Request (POST)

The request body is an [AddressRestRequest ](https://docs.mastersoftgroup.com/loqate-harmony-api/objects/address-objects#addressrestrequest)object:

* The `id`attribute is required

```json
{
    "payload": [ { "id": "GB|RM|A|123456" } ]
}   
```

#### Request Parameters (GET)

* The `id`parameter is required

#### Response

The response body is an [AddressRestResponse](https://docs.mastersoftgroup.com/loqate-harmony-api/objects/address-objects#addressrestresponse) object:

```json
   {
        "status": "SUCCESS",
        "messages": [],
        "payload": [
            {
                "fullAddress": "Prime Minister & First Lord of the Treasury, 10 Downing Street, LONDON, SW1A 2AA, UNITED KINGDOM",
                "country": "United Kingdom",
                "postcode": "SW1A 2AA",
                "street2": "",
                "street": "Downing Street",
                "streetNumber": "10",
                "postal": "",
                "postalType": "",
                "postalNumber": null,
                "buildingName": "",
                "subdwelling": "",
                "attributes": {
                    ...
                },
                "id": "GB|RM|A|12345678",
                "district": "",
                "city": "London",
                "province": ""
            }
        ]
    }
```