> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.repliers.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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:

| Query | Result |
|---|---|
| `city=Cambridge&city=Boston` | ✅ Works — returns listings in both cities |
| `city=Cambridge&neighborhood=Porter Square` | ✅ Works — neighborhood is within the specified city |
| `city=Boston&area=Suffolk` | ✅ Works — Boston is within Suffolk County, so the hierarchy is respected |
| `area=Middlesex&city=Boston` | ❌ Fails — Boston is not within Middlesex County |
| `city=Cambridge&city=Boston&neighborhood=Allston` | ❌ Fails — Allston belongs to Boston, but the API cannot resolve the city↔neighborhood pairing correctly when multiple cities are present |

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](https://help.repliers.com/en/article/locations-api-implementation-guide-s4c68b/) and the [API reference](https://docs.repliers.io/reference/get_locations).

### 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

```json
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
```

```json
{
  "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](https://help.repliers.com/en/article/bundled-searches-developer-guide-17x7tsa/).

---

## Which Solution Should I Use?

| Scenario | Recommended approach |
|---|---|
| Building a location picker / autocomplete UI | `locationId` via `/locations/autocomplete` |
| Known location IDs from a previous lookup | `locationId` parameter |
| Working with city/neighborhood names directly (no location lookup) | Bundled Searches |
| Complex filters that differ per location (e.g. different `minBedrooms` per city) | Bundled Searches |

---

## 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?