Locality lookups

Pass the postal code from an input field to the /address/lookup/v2/ endpoint specifying the required attributes. The necessary attributes depend on your usecase. For example in the USA, if you want to retrieve the associated city and state, specifiy postal_code, town, and region. postal_code is required for this type of lookup and town and region define which additional attributes should be returned for the input.

POST /address/lookup/v2 HTTP/1.1

{
    "country_iso": "USA",
    "datasets": [ "us-address" ],
    "key": {
        "type": "postal_code",
        "value": "90210"
    },
    "attributes": {
        "postal_code_lookup": [
            "postal_code",
            "town",
            "region"
        ]
    }
}

The response includes one or more suggestions with the specified attributes and keys to get Enrichment elements, like geocoordinates, at the locality or postal code level. Find a partial response below.

{
    "locality": {
        "region": { "code": "CA" },
        "town": { "name": "Beverly Hills" }
    },
    "postal_code": { "primary": "90210" },
    "postal_code_key": "aWQ9OTAyMTAsIFVuaXRlZCBTdGF0ZXMgT2YgQW1lcmljYX5hbHRfa2V5PX5kYXR",
    "locality_key": "aWQ9QmV2ZXJseSBIaWxscywgVW5pdGVkIFN0YXRlc"
}

Experian Address Validation will respond with an error should an attribute be requested that is not supported for the country, i.e. there are no districts in the USA.

Pass the locality information from an input field to the /address/lookup/v2/ endpoint specifying the required attributes. The necessary attributes depend on your usecase. For example in the UK, if you want to retrieve the available postal codes and county, specifiy town and subregion. town is required for this type of lookup and region defines which additional attribute should be returned for the input.

POST /address/lookup/v2 HTTP/1.1

{
    "country_iso": "gbr",
    "datasets": [ "gb-address" ],
    "key": {
        "type": "locality",
        "value": "hull"
    },
    "attributes": {
        "locality_lookup": [
            "town",
            "subregion"
        ]
    }
}

The response includes one or more suggestions with the specified attributes and keys to get Enrichment elements, like geocoordinates, at the locality or postal code level. postal_code_key is only available if the request contained the attribute postal_code. Find a partial response below.

{
    "locality": {
        "sub_region": { "name": "East Riding of Yorkshire", "description": "Geographic county" },
        "town": { "name": "Hull" }
    },
    "locality_key": "aWQ9SHVsbCwgRWFzdCBSaWRpbmcgb2YgWW9ya3NoaXJlLCBVbm"
}

The more granular attributes you request, i.e. including district or sub-district where available, the more suggestions will be returned as every suggestion will be split by the available values. For example, including district in the request above will increase the number of returned suggestions from 1 to over 80. The returned locality key will now be specific to the returned district, like "Bransholme" and "Kingswood" in Hull. Find a partial response below.

{
    "locality": {
        "sub_region": { "name": "East Riding of Yorkshire", "description": "Geographic county" },
        "town": { "name": "Hull" },
        "district": { "name": "Bransholme" }
    },
    "locality_key": "aWQ9QnJhbnNob2xtZSwgSHVsbCwgRWFzdCBSaWRpbmcgb2Yg"
},
{
    "locality": {
        "sub_region": { "name": "East Riding of Yorkshire", "description": "Geographic county" },
        "town": { "name": "Hull" },
        "district": { "name": "Kingswood" }
    },
    "locality_key": "aWQ9S2luZ3N3b29kLCBIdWxsLCBFYXN0IFJpZGluZyBvZiBZb"
}

Experian Address Validation will respond with an error should an attribute be requested that is not supported for the country, i.e. there are no districts in the USA.

Pass the locality information from an input field to the /address/lookup/v2/ endpoint.

POST /address/lookup/v2 HTTP/1.1

{
    "country_iso": "usa",
    "datasets": [
        "us-address"
    ],
    "key": {
        "type": "locality",
        "value": "Springfield"
    }
}

There are about 100 results returned - Springfield in Missouri, Oregon, Illinios, etc. All broken down further by subregion and postal code as no specific attributes have been defined. Even if you'd only be interested in the locality_key for your geocoder usecase, there would be 35 Springfields in different regions and subregions.

You can limit the returned results by supplying additional information. You have the option to search on a town in conjunction with the region they are located in, e.g. a city in a specific state in the USA. The example limits the results to a locality lookup of Springfield in Oregon.

POST /address/lookup/v2 HTTP/1.1

{
    "country_iso": "usa",
    "datasets": [
        "us-address"
    ],
    "key": {
        "type": "locality",
        "value": "Springfield, OR"
    }
}

Not specifying any specific attributes to include in the response will return a small number of postal codes for Springfield within the same county in Oregon. Find a partial response below.

{
    "locality": {
        "region": { "code": "OR" },
        "sub_region": { "name": "Lane" },
        "town": { "name": "Springfield" }
    },
    "postal_code": { "primary": "97477" },
    "postal_code_key": "Z2FrX3R5cGU9cG9zdGFsX2NvZGU",
    "locality_key": "aWQ9U3ByaW5nZmllbGQR5cGU9bG9jYWxpdHk"
}

Specifying only town, subregion, and region in the request would further reduce the number of results as it won't be split by postal code anymore. We suggest you define the relevant attributes for your usecase to ensure the least amount of suggestions is returned to the user, ensuring you do not combine towns across differnt subregions or regions into a single suggestion. In this case the locality_key is unlikely to lead to correct geocode information.

Experian Address Validation will respond with an error should an attribute be requested that is not supported for the country, i.e. there are no districts in the USA.