Postcoder now filters addresses by residential or commercial

Postcoder now lets you filter address search results by residential or non-residential categories across the UK and Ireland.

Product Daniel Cooper Published on 13 May 2025

Postcoder now lets you filter address search results by residential or non-residential categories across the UK and Ireland.

This enhancement applies to both address autocomplete and address and postcode lookup, so whichever method of address capture you use, you can benefit from greater control over what your users see.

We made this change in response to customer feedback, and hope it helps improve the experience you provide to your users.

Let's explore how it works.

Introducing the `usercategory` parameter

The autocomplete/find and address API endpoints now support a new optional query parameter: usercategory

You can set it to one of two values:

R to return only residential addresses
N to return only non-residential addresses

Example request

Here's an example autocomplete/find request for UK residential addresses matching "aviva":

/pcw/autocomplete/find?usercategory=R&query=aviva&country=uk&apikey=PCW45-12345-12345-1234X&singlesummary=true&format=json

Example response

[
    {
        "id": "6110808",
        "type": "ADD",
        "summaryline": "Aviva Cottage",
        "locationsummary": "Willington Road, Clotton, Tarporley, Cheshire, CW6 0UG",
        "count": 1,
        "usercategory": "R"
    },
    ...
    ...
]

From this example, you will see the autocomplete response includes the usercategory field when the filter is set; the field will have a value of either R for residential, N for non-residential or L for large organisations and businesses (although this last one only applies in the UK).

Show `usercategory` without filtering

If you want to include the usercategory field in the response without necessarily filtering the results, you can do so using the addtags parameter:

/pcw/autocomplete/find?addtags=usercategory&query=1%20birchwood&country=uk&apikey=PCW45-12345-12345-1234X&singlesummary=true&format=json

As mentioned above, the usercategory response field will have a value of either R for residential, N for non-residential or L for large organisations and businesses (UK only).

Use cases to consider

Here are some practical ways you can use the new filter:

Simplify address capture by removing irrelevant address types - for example, in B2C scenarios like opening a bank account or signing up for utilities, where only residential addresses are expected
Test UI enhancements by showing icons or labels for residential and non-residential addresses to help users more quickly recognise the type of address they're selecting

Naming: why `usercategory`?

The term usercategory originates from Royal Mail's address classification system in the UK. It reflects how each address is categorised based on who primarily uses it. Royal Mail use the classification to help with mail routing and logistical planning.

Since many Postcoder customers already include usercategory in their results via addtags=usercategory, we've used the same naming convention for filtering.

Coverage: why only UK and Ireland?

At this stage, filtering by residential and non-residential categories is only available for UK and Irish addresses because these are the countries where our global address data includes a reliable classification of address types.

Not all countries distinguish between residential and non-residential addresses in a consistent or meaningful way. Where this classification doesn't exist in our source data, we're unable to provide accurate filtering.

We're monitoring developments in other regions and may expand support as more countries introduce similar classifications. We'll keep you posted if we do.

Try it now

The new filtering feature is up and running - give it a go and let us know what you think. If it's useful, or if you've got ideas on how we can make Postcoder even better in future, we'd love to hear from you.