# Apartments Com Scraper (`leadsbrary/apartments-com-scraper`) Actor

From 1$/1000 results. Scrape Apartments.com listings by city, filter, or direct URL. Extract rent, address, beds, baths, amenities, photos, virtual tours & coordinates. Residential proxy needed for full detail mode.

- **URL**: https://apify.com/leadsbrary/apartments-com-scraper.md
- **Developed by:** [Alexandre Manguis](https://apify.com/leadsbrary) (community)
- **Categories:** Real estate, Integrations, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Apartments.com Scraper

> **From $1 per 1 000 listings** — search by city, filter, or paste any Apartments.com URL. No watermark. REST API ready.

---

### Proxy requirements

| Mode | Proxy needed |
|---|---|
| **Cards only** (`includeDetails: false`) | **Not required** — search pages are accessible without proxy on most runs |
| **Full detail** (`includeDetails: true`) | **Required** — detail pages are heavily protected and will be blocked without a residential proxy |

**Default mode is cards only** — no proxy needed to get started.

When you enable full detail, use your own residential proxies for reliable results. Datacenter proxies are blocked quickly.

```json
{
  "proxyConfiguration": {
    "proxyUrls": ["http://USERNAME:PASSWORD@YOUR-PROXY-HOST:PORT"]
  }
}
````

***

### What it does

Visit Apartments.com search and listing pages, collect results, and save structured data to a dataset. Two modes — choose the one that fits your workflow:

| Mode | How | Speed |
|---|---|---|
| **URL mode** | Paste any Apartments.com search, filter, map, or property URL | Fastest |
| **Builder mode** | Set city, home type, bedrooms, price, pets, amenities in the input form | No URL needed |

Both modes support pagination, detail-page extraction, keyword post-filtering, and optional proxy.

***

### What it extracts

#### From search result cards (fast mode)

| Field | Description |
|---|---|
| `url` | Listing URL |
| `propertyName` | Property name |
| `address` | Street address when visible |
| `price` | Rent text from the card |
| `beds` / `baths` / `sqft` | Size info |
| `phone` | Phone when shown on card |
| `amenities` | Amenities visible on the card |
| `image` | Card thumbnail URL |

#### From detail pages (full mode)

Everything above, plus:

| Field | Description |
|---|---|
| `rent` | Full rent range from the detail page |
| `rating` | Star rating text |
| `description` | Full property description |
| `highlights` | Property highlights section |
| `amenities` | Complete amenity list |
| `feesAndPolicies` | Fees, deposits, pet policy text |
| `schools` | Nearby schools & education info |
| `transportation` | Transit & commute info |
| `floorPlans` | Floor plan & availability text |
| `coordinates` | `{ latitude, longitude }` from page data |
| `images` | All photo URLs (toggle with `includeImages`) |
| `virtualTours` | Virtual tour, video & Matterport links |
| `source` | Origin search URL, page number |
| `scrapedAt` | ISO timestamp |

***

### Best use cases

- **Real-estate lead generation** — batch-pull landlord contact info (name, phone, address) for outreach
- **Market research** — track rent trends by city, bedroom count, or neighborhood
- **Competitive analysis** — monitor price changes and new listings in target markets
- **Data pipelines** — feed structured apartment data into CRMs, spreadsheets, or BI tools
- **Investment analysis** — compare rent-to-price ratios across neighborhoods
- **Relocation tools** — build curated shortlists with photos, floor plans, and amenity scores

***

### Quick start

1. Click **Try for free** (or call the API).
2. **Option A** — paste one or more Apartments.com URLs into **Start URLs**.\
   **Option B** — leave Start URLs empty and fill in **Locations**, **Bedrooms**, **Max rent**, etc.
3. Set **Maximum listings** to control run cost.
4. Click **Start** — results appear in the **Dataset** tab within minutes.

***

### Input

#### Targeting

| Field | Type | Default | Description |
|---|---|---|---|
| `startUrls` | array | — | Paste Apartments.com search, filter, map, or property detail URLs. Overrides builder inputs |
| `locations` | array | `["new-york-ny"]` | City slugs (e.g. `new-york-ny`, `miami-fl`, `chicago-il`) |
| `homeTypes` | array | `["all"]` | `all`, `apartments`, `houses`, `condos`, `townhomes` |
| `bedrooms` | array | — | `studios`, `1`, `2`, `3`, `4`, `5`, `min-2`, `min-3` |
| `priceMin` | integer | — | Minimum monthly rent |
| `priceMax` | integer | — | Maximum monthly rent |
| `petPolicy` | string | — | `pet-friendly`, `pet-friendly-dog`, `pet-friendly-cat` |
| `amenities` | array | — | Filter slugs: `washer-dryer`, `parking`, `pool`, `furnished`, etc. |
| `specialties` | array | — | `student-housing`, `senior-housing`, `short-term`, `low-income`, etc. |
| `extraFilterSlugs` | array | — | Any additional Apartments.com URL filter slugs |
| `rawQueryString` | string | — | Raw query string to append to generated URLs |
| `mapBoundingBoxToken` | string | — | Value for the `bb=` parameter from a map search |

#### Scraping options

| Field | Type | Default | Description |
|---|---|---|---|
| `maxItems` | integer | `100` | Max listings to save (0 = no limit) |
| `maxPages` | integer | `3` | Max search result pages per URL |
| `includeDetails` | boolean | `true` | Open each listing for full detail extraction |
| `includeImages` | boolean | `true` | Extract photo URLs from detail pages |
| `includeVirtualTours` | boolean | `true` | Extract virtual tour / video links |
| `saveHtml` | boolean | `false` | Save detail-page HTML to Key-Value Store for debugging |
| `maxConcurrency` | integer | `2` | Parallel pages (keep low without proxy) |
| `requestHandlerTimeoutSecs` | integer | `75` | Page timeout in seconds |
| `maxRequestRetries` | integer | `2` | Retries per URL |
| `keywords` | array | — | Post-filter: only save listings that match these keywords |
| `keywordMatchMode` | string | `any` | `any`, `all`, or `phrase` |
| `proxyConfiguration` | object | disabled | Apify Proxy or custom proxy URLs |

***

### URL builder examples

The actor builds Apartments.com URLs automatically. Here are a few examples:

| Input | Generated URL |
|---|---|
| `locations: ["new-york-ny"], bedrooms: ["2"], priceMax: 3000` | `/new-york-ny/2-bedrooms-under-3000/` |
| `locations: ["miami-fl"], homeTypes: ["apartments"], amenities: ["pool"]` | `/apartments/miami-fl/pool/` |
| `locations: ["austin-tx"], petPolicy: "pet-friendly-dog"` | `/austin-tx/pet-friendly-dog/` |
| `locations: ["chicago-il"], bedrooms: ["studios"]` | `/chicago-il/studios/` |

***

### Tips

**Fastest mode (card-only)**\
Set `includeDetails: false` to skip individual property pages. You get the search card data in seconds with no proxy needed for the first few pages.

**Avoiding blocks**\
Apartments.com protects against automated access. Enable **Apify Proxy** (residential recommended) when running at scale or when you see 403 errors.

**Map-area targeting**\
Copy a map search URL from the site (e.g. `https://www.apartments.com/?bb=_slx7yjq0H1g4mu2nD`) and paste it into **Start URLs** for precise geographic targeting.

**Keyword post-filter**\
Use `keywords` to keep only listings whose text matches. For example `["rooftop", "doorman"]` with `keywordMatchMode: any` saves only listings that mention at least one of those words.

**Pagination**\
`maxPages` controls how many search-result pages are visited per URL. Apartments.com uses `/2/`, `/3/` etc. as page slugs.

***

### Proxy settings

Proxies are disabled by default for low-volume runs. Enable them in the **Proxy** section when:

- You receive 403 / blocked errors
- Running at concurrency > 2
- Running more than a few hundred requests

Residential proxies give the best success rate on Apartments.com.

***

### Troubleshooting

| Symptom | Fix |
|---|---|
| 403 / blocked error | Enable Apify Proxy (residential) |
| Empty results | Check the URL or city slug is valid on Apartments.com |
| Missing detail fields | Some fields only appear on certain property types |
| Slow run | Lower `maxConcurrency`; enable proxy |
| Dataset has fewer rows than expected | Some cards on the page may be ads or have no property URL |

***

### Keywords

apartments.com scraper · rental listings · apartment search api · rent data · real estate leads · property scraper · apartment data extraction · rental market research

### Best way to target data

#### Option A: paste exact Apartments.com URLs

Use `startUrls` when you already have the URL you want from Apartments.com. This is the safest and most precise targeting mode.

Examples:

```text
https://www.apartments.com/new-york-ny/
https://www.apartments.com/new-york-ny/2-bedrooms/
https://www.apartments.com/new-york-ny/under-3000/
https://www.apartments.com/new-york-ny/washer-dryer/
https://www.apartments.com/new-york-ny/min-2-bedrooms-under-3000/
https://www.apartments.com/houses/miami-fl/
https://www.apartments.com/condos/chicago-il/
https://www.apartments.com/townhomes/austin-tx/
https://www.apartments.com/toronto-on/
https://www.apartments.com/?bb=_slx7yjq0H1g4mu2nD
```

You can also paste a property detail URL. The Actor will detect it and scrape it as a detail page.

#### Option B: use the URL builder inputs

Leave `startUrls` empty and fill the targeting fields:

```json
{
  "locations": ["new-york-ny"],
  "homeTypes": ["all"],
  "bedrooms": ["2"],
  "priceMax": 3000,
  "amenities": ["washer-dryer"],
  "maxItems": 50,
  "maxPages": 2,
  "includeDetails": true,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

This builds:

```text
https://www.apartments.com/new-york-ny/2-bedrooms-under-3000/washer-dryer/
```

### Tested URL patterns

#### City or area

```text
https://www.apartments.com/new-york-ny/
https://www.apartments.com/miami-fl/
https://www.apartments.com/toronto-on/
```

Use the same city slug format Apartments.com uses in its URLs. For US cities, that is usually `city-state`, for example `new-york-ny`. Canada-style pages such as `toronto-on` are also supported when the site supports them.

#### Map / zone targeting

Apartments.com map searches can use a `bb` parameter:

```text
https://www.apartments.com/?bb=_slx7yjq0H1g4mu2nD
```

For map searches, the most reliable method is to copy the full URL from Apartments.com and paste it into `startUrls`.

You can also use:

```json
{
  "mapBoundingBoxToken": "_slx7yjq0H1g4mu2nD"
}
```

or:

```json
{
  "rawQueryString": "bb=_slx7yjq0H1g4mu2nD"
}
```

But exact copied URLs are recommended for custom drawn map areas.

#### Property type

Supported `homeTypes` values:

```text
all
apartments
houses
condos
townhomes
```

Examples:

```text
https://www.apartments.com/apartments/miami-fl/
https://www.apartments.com/houses/miami-fl/
https://www.apartments.com/condos/chicago-il/
https://www.apartments.com/townhomes/austin-tx/
```

`all` means no property-type prefix:

```text
https://www.apartments.com/miami-fl/
```

#### Bedrooms

Supported builder values:

```text
studios
1
2
3
4
5
min-2
min-3
```

Examples:

```text
https://www.apartments.com/new-york-ny/studios/
https://www.apartments.com/new-york-ny/1-bedrooms/
https://www.apartments.com/new-york-ny/2-bedrooms/
https://www.apartments.com/new-york-ny/3-bedrooms/
https://www.apartments.com/new-york-ny/min-2-bedrooms/
```

#### Price filters

The builder supports:

```text
priceMax only -> under-3000
priceMin only -> over-2000
priceMin + priceMax -> 2000-to-3000
```

Examples:

```text
https://www.apartments.com/new-york-ny/under-3000/
https://www.apartments.com/new-york-ny/over-3000/
https://www.apartments.com/new-york-ny/2000-to-3000/
https://www.apartments.com/new-york-ny/min-2-bedrooms-under-3000/
https://www.apartments.com/new-york-ny/studios-under-3000/
```

#### Pets

Use `petPolicy`:

```text
pet-friendly
pet-friendly-dog
pet-friendly-cat
```

Examples:

```text
https://www.apartments.com/new-york-ny/pet-friendly/
https://www.apartments.com/new-york-ny/pet-friendly-dog/
https://www.apartments.com/new-york-ny/pet-friendly-cat/
```

#### Amenities

Use `amenities` as raw Apartments.com slugs. Common examples:

```text
washer-dryer
parking
air-conditioning
furnished
utilities-included
dishwasher
pool
fitness-center
laundry-facilities
balcony
hardwood-floors
wheelchair-access
elevator
gated
controlled-access
recent-build
```

Examples:

```text
https://www.apartments.com/new-york-ny/washer-dryer/
https://www.apartments.com/new-york-ny/parking/
https://www.apartments.com/new-york-ny/air-conditioning/
https://www.apartments.com/new-york-ny/furnished/
```

#### Specialty housing

Use `specialties`:

```text
student-housing
senior-housing
short-term
low-income
military-housing
corporate-housing
```

Examples:

```text
https://www.apartments.com/new-york-ny/senior-housing/
https://www.apartments.com/new-york-ny/short-term/
https://www.apartments.com/new-york-ny/low-income/
```

#### Extra filters

If Apartments.com supports a URL slug that is not exposed as a named input, put it in `extraFilterSlugs`.

Example:

```json
{
  "locations": ["new-york-ny"],
  "extraFilterSlugs": ["recent-build", "controlled-access"]
}
```

### Pagination

Search result pagination usually uses a numeric path segment:

```text
https://www.apartments.com/new-york-ny/2/
https://www.apartments.com/new-york-ny/2-bedrooms/2/
https://www.apartments.com/houses/miami-fl/2/
```

### Input reference

#### `startUrls`

Array of Apartments.com URLs. This has highest priority. If provided, the Actor uses these URLs instead of generating URLs from `locations`.

Use this for:

- exact city searches
- exact filter searches
- copied map searches
- custom Apartments.com searches
- property detail pages

#### `locations`

Array of city or area slugs.

Examples:

```text
new-york-ny
miami-fl
austin-tx
toronto-on
```

You can also type human text like `New York, NY`; the Actor converts it to `new-york-ny`.

#### `homeTypes`

Array. Use one or more:

```text
all
apartments
houses
condos
townhomes
```

#### `bedrooms`

Array. Empty means any bedrooms.

Examples:

```text
studios
1
2
3
min-2
```

#### `priceMin` and `priceMax`

Optional integers.

Examples:

```json
{ "priceMax": 3000 }
{ "priceMin": 2000 }
{ "priceMin": 2000, "priceMax": 3000 }
```

#### `petPolicy`

Optional string:

```text
pet-friendly
pet-friendly-dog
pet-friendly-cat
```

#### `amenities`

Array of URL slugs such as `washer-dryer`, `parking`, `pool`, `furnished`.

#### `specialties`

Array of URL slugs such as `senior-housing`, `short-term`, `low-income`.

#### `extraFilterSlugs`

Array of any additional URL segments to append.

#### `rawQueryString`

Optional raw query string without `?`.

Example:

```text
bb=_slx7yjq0H1g4mu2nD
```

#### `mapBoundingBoxToken`

Optional value for the `bb` parameter only.

Example:

```text
_slx7yjq0H1g4mu2nD
```

#### `maxItems`

Maximum listings to save. Use `0` for no explicit limit.

#### `maxPages`

Maximum search result pages to visit per search URL.

#### `includeDetails`

When true, the Actor opens each detail page and extracts richer data. This is slower but better.

#### `includeImages`

Extracts image URLs from detail pages.

#### `includeVirtualTours`

Extracts visible virtual tour, video, Matterport, iframe, YouTube, and Vimeo links.

#### `saveHtml`

Saves detail page HTML snapshots in the default key-value store. Useful for debugging or selector updates.

#### `maxConcurrency`

Default is `2`. Keep it low without proxies.

#### `requestHandlerTimeoutSecs`

Default is `75` seconds.

#### `maxRequestRetries`

Default is `2` retries.

#### `keywords`

Optional post-filter. The Actor first extracts data, then checks whether the extracted text contains your keywords.

This is useful for filtering results such as:

```text
garage
no fee
dog friendly
washer dryer
near subway
```

For native Apartments.com keyword searches, use the Apartments.com website, copy the resulting URL, and paste it into `startUrls`.

#### `keywordMatchMode`

Use one of:

```text
any
all
phrase
```

- `any`: save listing if at least one keyword matches
- `all`: save listing only if every keyword matches
- `phrase`: same as all, but intended for exact phrases such as `washer dryer`

#### `proxyConfiguration`

This input is intentionally last.

Default:

```json
{
  "useApifyProxy": false
}
```

So by default the Actor uses **no proxies**.

Enable Apify Proxy or custom proxies only if Apartments.com blocks or throttles the run. When using no proxy, keep `maxConcurrency` low.

### Output example

```json
{
  "id": "abc1234",
  "url": "https://www.apartments.com/example-property-city-st/abc1234/",
  "propertyName": "Example Apartments",
  "address": "123 Main St, New York, NY 10001",
  "phone": "(555) 123-4567",
  "rent": "$2,500 - $3,800",
  "beds": "1-2 Beds",
  "baths": "1-2 Baths",
  "sqft": "650 - 1,100 Sq Ft",
  "coordinates": {
    "latitude": 40.7128,
    "longitude": -74.006
  },
  "description": "Property description text...",
  "amenities": ["Washer & Dryer", "Parking", "Fitness Center"],
  "images": [
    { "url": "https://...jpg", "alt": "Example Apartments" }
  ],
  "virtualTours": [],
  "source": {
    "type": "detail",
    "searchUrl": "https://www.apartments.com/new-york-ny/",
    "searchPage": 1,
    "startUrl": null
  },
  "scrapedAt": "2026-05-20T00:00:00.000Z"
}
```

### How to run on Apify

#### Upload ZIP in Apify Console

1. Open Apify Console.
2. Create a new Actor.
3. Choose upload from ZIP or import source files.
4. Upload this package.
5. Build the Actor.
6. Open the Input tab and set your URLs or builder fields.
7. Run it.

#### Run locally

```bash
npm install
npm start
```

With a local input file, use Apify CLI storage or set the default input in local storage.

### Files included

```text
.actor/actor.json
Dockerfile
INPUT_SCHEMA.json
README.md
package.json
sample-input.json
src/main.js
src/url-builder.js
src/extractors.js
src/keyword-filter.js
test/url-builder.test.js
test/keyword-filter.test.js
```

### Validation included

The package includes simple unit tests for:

- URL generation
- location slug normalization
- bedroom and price filters
- pagination URL generation
- property URL detection
- keyword filtering

Run:

```bash
npm test
npm run check
```

### Practical recipes

#### Scrape New York apartments under 3000 USD

```json
{
  "startUrls": [],
  "locations": ["new-york-ny"],
  "homeTypes": ["all"],
  "priceMax": 3000,
  "maxItems": 100,
  "maxPages": 3,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

#### Scrape Miami houses, pet friendly

```json
{
  "startUrls": [],
  "locations": ["miami-fl"],
  "homeTypes": ["houses"],
  "petPolicy": "pet-friendly",
  "maxItems": 100,
  "maxPages": 3,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

#### Scrape Toronto rentals

```json
{
  "startUrls": [],
  "locations": ["toronto-on"],
  "homeTypes": ["all"],
  "maxItems": 100,
  "maxPages": 3,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

#### Scrape an exact map area

```json
{
  "startUrls": [
    { "url": "https://www.apartments.com/?bb=_slx7yjq0H1g4mu2nD" }
  ],
  "maxItems": 100,
  "maxPages": 3,
  "includeDetails": true,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

#### Use a custom URL from Apartments.com filters

```json
{
  "startUrls": [
    { "url": "https://www.apartments.com/new-york-ny/2-bedrooms/washer-dryer/" }
  ],
  "maxItems": 100,
  "maxPages": 3,
  "includeDetails": true,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

### Troubleshooting

#### The run returns few or no results

Try these steps:

1. Open the URL manually in a browser to verify it has results.
2. Paste the exact Apartments.com URL in `startUrls` instead of using builder fields.
3. Increase `maxPages`.
4. Disable `keywords` temporarily.
5. Enable proxies if the page is blocked.

#### The site blocks the run

Apartments.com may apply anti-bot or security checks. Try:

- lower `maxConcurrency`
- enable Apify Proxy
- use residential proxies if your Apify plan allows it
- reduce `maxPages`
- use fewer start URLs per run

#### A filter is missing

Use Apartments.com in your browser, select the filter, copy the resulting URL, and paste it into `startUrls`.

Or copy only the filter slug into `extraFilterSlugs`.

### Notes for maintainers

- List extraction is intentionally generic and avoids relying on one fragile CSS class.
- Detail extraction combines JSON-LD, meta tags, visible text sections, image tags, and links.
- The Actor stores a `RUN-SUMMARY` object in the default key-value store after each run.
- If Apartments.com changes its layout, enable `saveHtml` and inspect the saved HTML snapshots.

### Keywords

apartments.com scraper, apartments scraper, apify apartments actor, apartments.com apify actor, apartments.com crawler, apartment listings scraper, rental listings scraper, real estate scraper, property scraper, apartments.com rentals, apartments.com search scraper, apartments.com detail scraper, apartments.com map scraper, apartments.com city scraper, apartments.com houses scraper, apartments.com condos scraper, apartments.com townhomes scraper, apartments.com pet friendly scraper, apartments.com washer dryer scraper, apartments.com rent data, apartments.com listings data, apartments.com rental data, apartments.com url scraper, apartments.com playwright scraper, apartments.com crawlee scraper

# Actor input Schema

## `startUrls` (type: `array`):

Highest priority. Paste Apartments.com search URLs, map URLs with ?bb=..., filter URLs, pagination URLs, or property detail URLs. When provided, the actor uses these URLs first.

## `locations` (type: `array`):

City or area slugs. Examples: new-york-ny, Miami FL, toronto-on, Austin, TX. Ignored when you rely only on Start URLs.

## `homeTypes` (type: `array`):

Use: all, apartments, houses, condos, townhomes. all means no type prefix in the URL.

## `bedrooms` (type: `array`):

Optional. Use studios, 1, 2, 3, 4, 5, min-2, min-3. Empty means any bedrooms.

## `priceMin` (type: `integer`):

Optional minimum monthly rent. Example: 2000. Used with priceMax to build /2000-to-3000/ or alone as /over-2000/.

## `priceMax` (type: `integer`):

Optional maximum monthly rent. Example: 3000 builds /under-3000/ when no minimum is set.

## `petPolicy` (type: `string`):

Optional. Use empty, pet-friendly, pet-friendly-dog, or pet-friendly-cat.

## `amenities` (type: `array`):

Optional filter slugs. Examples: washer-dryer, parking, air-conditioning, furnished, utilities-included, pool, fitness-center, laundry-facilities.

## `specialties` (type: `array`):

Optional filter slugs. Examples: student-housing, senior-housing, short-term, low-income, military-housing, corporate-housing.

## `extraFilterSlugs` (type: `array`):

Advanced: raw URL segments to append. Example: controlled-access, elevator, recent-build. Use this for any Apartments.com filter not listed above.

## `rawQueryString` (type: `string`):

Optional raw query string to append to generated URLs, without the leading ?. Example: bb=\_slx7yjq0H1g4mu2nD. For exact map URLs, Start URLs are safer.

## `mapBoundingBoxToken` (type: `string`):

Optional value for the Apartments.com bb parameter. Example: \_slx7yjq0H1g4mu2nD. This is mainly for copied map searches.

## `maxItems` (type: `integer`):

Maximum number of listings to save. Set 0 for no explicit limit.

## `maxPages` (type: `integer`):

Search pages to visit per generated or provided search URL. Page 2 is normally /2/ in Apartments.com URLs.

## `includeDetails` (type: `boolean`):

When enabled, the actor opens each property page and extracts richer data. Requires a residential proxy. Disable for faster card-only output (no proxy needed).

## `includeImages` (type: `boolean`):

Extract image URLs from detail pages.

## `includeVirtualTours` (type: `boolean`):

Extract virtual tour, video, Matterport, iframe, and similar links when visible on the detail page.

## `saveHtml` (type: `boolean`):

Stores raw detail page HTML in the key-value store for debugging. Off by default to save storage.

## `maxConcurrency` (type: `integer`):

How many browser pages to run in parallel. Keep low when not using proxies.

## `requestHandlerTimeoutSecs` (type: `integer`):

Timeout for each page handler.

## `maxRequestRetries` (type: `integer`):

Retries for blocked, timed out, or failed pages.

## `keywords` (type: `array`):

Optional post-filter. Listings are saved only when their extracted text matches these keywords. For native Apartments.com keyword searches, paste the exact site URL in Start URLs.

## `keywordMatchMode` (type: `string`):

any = at least one keyword must match. all = every keyword must match. phrase = exact phrase matching for each keyword.

## `proxyConfiguration` (type: `object`):

Default is no proxy. Enable Apify Proxy or add custom proxies only if the site blocks or throttles your run.

## Actor input object example

```json
{
  "startUrls": [],
  "locations": [
    "new-york-ny"
  ],
  "homeTypes": [
    "all"
  ],
  "bedrooms": [],
  "amenities": [],
  "specialties": [],
  "extraFilterSlugs": [],
  "maxItems": 100,
  "maxPages": 3,
  "maxConcurrency": 2,
  "requestHandlerTimeoutSecs": 90,
  "maxRequestRetries": 2,
  "keywords": [],
  "keywordMatchMode": "any",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset with one row per Apartments.com listing: rent, address, beds, baths, amenities, coordinates and more.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [],
    "locations": [
        "new-york-ny"
    ],
    "homeTypes": [
        "all"
    ],
    "bedrooms": [],
    "petPolicy": "",
    "amenities": [],
    "specialties": [],
    "extraFilterSlugs": [],
    "rawQueryString": "",
    "mapBoundingBoxToken": "",
    "maxItems": 100,
    "maxPages": 3,
    "includeDetails": false,
    "includeImages": false,
    "includeVirtualTours": false,
    "saveHtml": false,
    "maxConcurrency": 2,
    "requestHandlerTimeoutSecs": 90,
    "maxRequestRetries": 2,
    "keywords": [],
    "keywordMatchMode": "any",
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("leadsbrary/apartments-com-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startUrls": [],
    "locations": ["new-york-ny"],
    "homeTypes": ["all"],
    "bedrooms": [],
    "petPolicy": "",
    "amenities": [],
    "specialties": [],
    "extraFilterSlugs": [],
    "rawQueryString": "",
    "mapBoundingBoxToken": "",
    "maxItems": 100,
    "maxPages": 3,
    "includeDetails": False,
    "includeImages": False,
    "includeVirtualTours": False,
    "saveHtml": False,
    "maxConcurrency": 2,
    "requestHandlerTimeoutSecs": 90,
    "maxRequestRetries": 2,
    "keywords": [],
    "keywordMatchMode": "any",
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("leadsbrary/apartments-com-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [],
  "locations": [
    "new-york-ny"
  ],
  "homeTypes": [
    "all"
  ],
  "bedrooms": [],
  "petPolicy": "",
  "amenities": [],
  "specialties": [],
  "extraFilterSlugs": [],
  "rawQueryString": "",
  "mapBoundingBoxToken": "",
  "maxItems": 100,
  "maxPages": 3,
  "includeDetails": false,
  "includeImages": false,
  "includeVirtualTours": false,
  "saveHtml": false,
  "maxConcurrency": 2,
  "requestHandlerTimeoutSecs": 90,
  "maxRequestRetries": 2,
  "keywords": [],
  "keywordMatchMode": "any",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call leadsbrary/apartments-com-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=leadsbrary/apartments-com-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Apartments Com Scraper",
        "description": "From 1$/1000 results. Scrape Apartments.com listings by city, filter, or direct URL. Extract rent, address, beds, baths, amenities, photos, virtual tours & coordinates. Residential proxy needed for full detail mode.",
        "version": "0.1",
        "x-build-id": "R9aBVwV9lIt5Ybfho"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/leadsbrary~apartments-com-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-leadsbrary-apartments-com-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/leadsbrary~apartments-com-scraper/runs": {
            "post": {
                "operationId": "runs-sync-leadsbrary-apartments-com-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/leadsbrary~apartments-com-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-leadsbrary-apartments-com-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "startUrls": {
                        "title": "Start URLs",
                        "type": "array",
                        "description": "Highest priority. Paste Apartments.com search URLs, map URLs with ?bb=..., filter URLs, pagination URLs, or property detail URLs. When provided, the actor uses these URLs first.",
                        "items": {
                            "type": "object",
                            "required": [
                                "url"
                            ],
                            "properties": {
                                "url": {
                                    "type": "string",
                                    "title": "URL of a web page",
                                    "format": "uri"
                                }
                            }
                        }
                    },
                    "locations": {
                        "title": "Locations",
                        "type": "array",
                        "description": "City or area slugs. Examples: new-york-ny, Miami FL, toronto-on, Austin, TX. Ignored when you rely only on Start URLs.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "homeTypes": {
                        "title": "Home types",
                        "type": "array",
                        "description": "Use: all, apartments, houses, condos, townhomes. all means no type prefix in the URL.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "bedrooms": {
                        "title": "Bedrooms",
                        "type": "array",
                        "description": "Optional. Use studios, 1, 2, 3, 4, 5, min-2, min-3. Empty means any bedrooms.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "priceMin": {
                        "title": "Minimum rent",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Optional minimum monthly rent. Example: 2000. Used with priceMax to build /2000-to-3000/ or alone as /over-2000/."
                    },
                    "priceMax": {
                        "title": "Maximum rent",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Optional maximum monthly rent. Example: 3000 builds /under-3000/ when no minimum is set."
                    },
                    "petPolicy": {
                        "title": "Pet policy",
                        "type": "string",
                        "description": "Optional. Use empty, pet-friendly, pet-friendly-dog, or pet-friendly-cat."
                    },
                    "amenities": {
                        "title": "Amenities",
                        "type": "array",
                        "description": "Optional filter slugs. Examples: washer-dryer, parking, air-conditioning, furnished, utilities-included, pool, fitness-center, laundry-facilities.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "specialties": {
                        "title": "Specialty housing",
                        "type": "array",
                        "description": "Optional filter slugs. Examples: student-housing, senior-housing, short-term, low-income, military-housing, corporate-housing.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "extraFilterSlugs": {
                        "title": "Extra filter slugs",
                        "type": "array",
                        "description": "Advanced: raw URL segments to append. Example: controlled-access, elevator, recent-build. Use this for any Apartments.com filter not listed above.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "rawQueryString": {
                        "title": "Raw query string",
                        "type": "string",
                        "description": "Optional raw query string to append to generated URLs, without the leading ?. Example: bb=_slx7yjq0H1g4mu2nD. For exact map URLs, Start URLs are safer."
                    },
                    "mapBoundingBoxToken": {
                        "title": "Map bounding box token",
                        "type": "string",
                        "description": "Optional value for the Apartments.com bb parameter. Example: _slx7yjq0H1g4mu2nD. This is mainly for copied map searches."
                    },
                    "maxItems": {
                        "title": "Maximum listings",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Maximum number of listings to save. Set 0 for no explicit limit."
                    },
                    "maxPages": {
                        "title": "Maximum search result pages per search URL",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Search pages to visit per generated or provided search URL. Page 2 is normally /2/ in Apartments.com URLs."
                    },
                    "includeDetails": {
                        "title": "Open listing detail pages",
                        "type": "boolean",
                        "description": "When enabled, the actor opens each property page and extracts richer data. Requires a residential proxy. Disable for faster card-only output (no proxy needed)."
                    },
                    "includeImages": {
                        "title": "Include images",
                        "type": "boolean",
                        "description": "Extract image URLs from detail pages."
                    },
                    "includeVirtualTours": {
                        "title": "Include virtual tours and videos",
                        "type": "boolean",
                        "description": "Extract virtual tour, video, Matterport, iframe, and similar links when visible on the detail page."
                    },
                    "saveHtml": {
                        "title": "Save detail HTML snapshots",
                        "type": "boolean",
                        "description": "Stores raw detail page HTML in the key-value store for debugging. Off by default to save storage."
                    },
                    "maxConcurrency": {
                        "title": "Max concurrency",
                        "minimum": 1,
                        "maximum": 20,
                        "type": "integer",
                        "description": "How many browser pages to run in parallel. Keep low when not using proxies."
                    },
                    "requestHandlerTimeoutSecs": {
                        "title": "Request timeout in seconds",
                        "minimum": 15,
                        "maximum": 300,
                        "type": "integer",
                        "description": "Timeout for each page handler."
                    },
                    "maxRequestRetries": {
                        "title": "Max request retries",
                        "minimum": 0,
                        "maximum": 10,
                        "type": "integer",
                        "description": "Retries for blocked, timed out, or failed pages."
                    },
                    "keywords": {
                        "title": "Keywords",
                        "type": "array",
                        "description": "Optional post-filter. Listings are saved only when their extracted text matches these keywords. For native Apartments.com keyword searches, paste the exact site URL in Start URLs.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "keywordMatchMode": {
                        "title": "Keyword match mode",
                        "enum": [
                            "any",
                            "all",
                            "phrase"
                        ],
                        "type": "string",
                        "description": "any = at least one keyword must match. all = every keyword must match. phrase = exact phrase matching for each keyword."
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Default is no proxy. Enable Apify Proxy or add custom proxies only if the site blocks or throttles your run."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```