Location Filter Conflicts: Searching Across Areas, Cities and Neighborhoods

Overview

When building location-based search, you might want to let users search across locations that don't share a clean parent-child relationship — for example, a neighborhood in one city alongside a neighborhood or city in another, or an area combined with a neighborhood that isn't within it. This article explains why standard query parameters fall short in these cases, and walks through the two approaches that work reliably.

Why Mixed Location Filters Can Fail

The Repliers API supports repeating location parameters (area, city, neighborhood) to filter across multiple locations. However, there's an important constraint: each location parameter is implicitly scoped to its parent in the hierarchy.

The location hierarchy is: area → city → neighborhood. A neighborhood filter is scoped to the city it belongs to, and a city filter is scoped to the area it belongs to. When the parameters you pass span different branches of this hierarchy, the API cannot resolve the pairings correctly.

This means:

In short, location filters must respect the area → city → neighborhood hierarchy within a single GET request. Mixing locations from different branches of this hierarchy will result in no matches or unexpected results.

Solution 1: Use locationId (Recommended)

The cleanest solution is to use the locationId parameter, which allows you to pass any combination of locations — cities, neighborhoods, or areas — regardless of their parent-child relationships.

Each locationId represents a precise geographic area. The API resolves it internally into the appropriate address components, so you don't have to worry about city/neighborhood pairing at all.

How to get locationId values

Use either of these endpoints to look up location IDs by name:

• GET /locations — filterable search by name, type, city, area, and more
• GET /locations/autocomplete — relevance-based typeahead lookup, ideal for search inputs

For full usage details, see the Locations API Implementation Guide and the API reference.

Example request

GET /listings?locationId=UPNSZPNOSMABOG&locationId=BTEARMALQUSNHK

This fetches listings from two distinct neighborhoods (e.g., one in Boston, one in Cambridge) in a single call, without any city/neighborhood conflict.

Why this is the preferred approach

• No manual city↔neighborhood pairing required
• Works for any combination of geographic areas
• Pairs naturally with autocomplete-driven location pickers in your UI
• Reduces ambiguity and edge cases in your filtering logic

Solution 2: Use Bundled Searches

If using the /locations endpoints isn't an option — for example, if you're working with pre-set location filters or constructing queries programmatically — you can use Bundled Searches to combine multiple independent queries into a single API call.

With Bundled Searches, each query in the bundle is fully self-contained. You specify the city and neighborhood together within the same query object, so there's no cross-contamination between location filters.

How it works

Instead of a GET request, you make a POST to /listings with a queries array in the request body. Each object in the array is an independent set of filters.

Example request

POST /listings

{
  "queries": [
    {
      "city": "Boston",
      "neighborhood": "Allston"
    },
    {
      "city": "Cambridge",
      "neighborhood": "Porter Square"
    }
  ]
}

This returns a single merged result set containing listings from both neighborhoods.

Adding shared filters

Query string parameters applied to the URL are global and affect all queries in the bundle. This is useful for things like status, pagination, or sorting:

POST /listings?status=A&resultsPerPage=50&sortBy=listPriceDesc

{
  "queries": [
    {
      "city": "Boston",
      "neighborhood": "South Boston"
    },
    {
      "city": "Cambridge"
    }
  ]
}

Here, status=A and sorting/pagination apply to both queries in the bundle.

For a full reference on Bundled Searches, see the Bundled Searches Developer Guide.

Which Solution Should I Use?

What questions does this article answer?

• Can I filter by a city and a neighborhood from a different city in the same query?
• Why does my city + neighborhood query return no results when they're from different cities?
• What is locationId and how do I use it to search across multiple areas?
• How do I use Bundled Searches to combine location-specific filters?
• What's the difference between using locationId and Bundled Searches for multi-location queries?

Updated on: 30/04/2026