# Apartments Properties and Details Scraper (`realestateapi/apartments-properties-and-details-scraper`) Actor

Permission-gated Apartments.com rental-listing parser. It makes no source requests unless prior written authorization is confirmed.

- **URL**: https://apify.com/realestateapi/apartments-properties-and-details-scraper.md
- **Developed by:** [Real Estate API](https://apify.com/realestateapi) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 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.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Apartments Properties and Details Scraper

Contains a parser for rental listings from official Apartments.com pages using HTTPS and Cheerio parsing of HTML, JSON-LD, and embedded JSON. The current Terms of Service (last updated July 11, 2025) restrict copying site materials without prior written consent and prohibit robots, spiders, and other automatic devices from accessing, monitoring, or copying pages for unauthorized purposes. No applicable written authorization is recorded. The Actor therefore makes zero source requests by default, finishes `SUCCEEDED` with `collectionStatus: SKIPPED_POLICY`, and writes no dataset rows.

`OUTPUT_SUMMARY.status` and `runStatus` use only `SUCCEEDED` or `FAILED`. Summaries include bounded generic `failureReasons`, or a `policyReason` when the no-request gate skips collection. A valid empty search finishes successfully without a placeholder row. A request or parsing failure before real listing data is saved finishes `FAILED`; if a later request, detail fetch, or dataset write fails after one or more real listings have been saved, the run remains `SUCCEEDED` with `collectionStatus: PARTIAL` and the saved listing count. Errors and access challenges are never written as dataset records.

Each dataset record must have an Apartments.com property URL and at least one source-backed property fact such as price, bedrooms, bathrooms, floor area, neighborhood, street address, or property description. Page titles, search-shell JSON-LD, and title/link-only cards are rejected. An explicit no-results page is a successful empty search; an unrecognized page with no valid listings is a failed run.

### Behavior

- Uses a fixed transparent ApifyActor/1.0 user agent and direct public HTTPS transport.
- `authorizationConfirmed` defaults to `false`; set it to true only when current written permission expressly covers automated collection and reuse. The checkbox is an operator attestation and does not grant permission.
- Does not follow redirects, solve verification challenges, or use proxy transport.
- Supports location fallback, caller-supplied official URLs, bounded pagination, optional source-linked detail pages, public review objects, and price/bedroom filters.
- Extracts listing identity, property URLs, IDs, addresses, rent ranges, beds, baths, square footage, property type, amenities, images, ratings, availability, phone values, reviews, and response evidence when exposed.
- Omits null, blank, and empty values from every dataset record.
- Writes OUTPUT_SUMMARY to the default key-value store.
- Records failure and policy-skip status only in `OUTPUT_SUMMARY`; it emits only source-backed `property_listing` dataset records.

### Input

| Field | Type | Description |
|---|---|---|
| authorizationConfirmed | boolean | Prior written permission attestation, default false |
| startUrls | array | Official HTTPS Apartments.com URLs |
| location | string | Fallback path slug, default chicago-il |
| zip / query | string | Optional run provenance for callers using ZIP or search input |
| includeDetails | boolean | Fetch source-linked public detail pages, default true |
| includeReviews | boolean | Retain public review objects, default false |
| maxReviews | integer | Maximum review objects per listing, default 20 |
| maxItems | integer | Maximum source-backed listings, default 50 |
| maxPages | integer | Maximum direct listing pages per start URL, default 5 |
| minPrice / maxPrice | number | Optional monthly-price filters |
| minBedrooms / maxBedrooms | number | Optional bedroom-range filters |
| requestDelayMs | integer | Bounded pacing delay, default 250 |
| timeoutSecs | integer | Direct request timeout, default 45 |

#### Example

```json
{
  "location": "chicago-il",
  "includeDetails": true,
  "maxItems": 50,
  "maxPages": 5
}
```

The complete field contract is in .actor/dataset_schema.json. Source-specific rental fields are emitted only when supported by an authorized public response; access failures never create fabricated listings.

### Offline validation

`npm test`, `npm run lint`, and `apify validate-schema` validate offline run-status behavior, JavaScript syntax, and Actor schemas. They do not establish current property data or grant permission. No live Actor run is documented until written authorization is on file.

### Code structure

The `src/main.js` entrypoint only starts the Actor lifecycle. Configuration, input normalization, direct HTTP access, HTML/JSON-LD parsing, record shaping, and run orchestration live in focused modules under `src/`, so each part can be reviewed and tested independently.

### Runtime dependency remediation — October 3, 2026

This bounded implementation only uses JSON input, dataset appends, JSON key-value storage and (where needed) dataset counts. Its project-local `src/platform.js` now uses the official Apify REST storage contract in Cloud and SDK-compatible local JSON files, with Apify’s censoring logger. Removing the unused full SDK/Crawlee runtime removes its transitive crawler, cache, FTP and proxy dependency graph; it does not claim that those vulnerable paths were unreachable. Source permission gates, transport restrictions, output fields and historical storage are preserved. The adapter does not implement queues, migration, automatic retries or non-JSON storage; no such methods are used by this Actor. Tokens remain environment-only bearer headers to the fixed official API host.

The Docker build uses Node 24 and deterministic `npm ci --omit=dev --ignore-scripts`. `npm run test:platform` verifies local append/preservation, Cloud storage routing and authenticated write failures. Existing parser/policy tests remain necessary. Technical dependency remediation and a no-request gate run do not qualify live source extraction.

# Actor input Schema

## `authorizationConfirmed` (type: `boolean`):

Set true only if current written permission covers automated collection and copying of Apartments.com materials. This checkbox is an operator attestation and does not grant permission.

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

Official HTTPS Apartments.com listing, search, or property-detail URLs.

## `urls` (type: `array`):

Backward-compatible alternative to startUrls. Use official HTTPS Apartments.com URLs only.

## `start_urls` (type: `array`):

Backward-compatible alternative to startUrls. Use official HTTPS Apartments.com URLs only.

## `url` (type: `string`):

Backward-compatible single-URL alternative to startUrls. Use an official HTTPS Apartments.com URL.

## `location` (type: `string`):

Apartments.com path slug used when startUrls is empty, such as chicago-il.

## `zip` (type: `string`):

Optional ZIP query retained as run provenance when a start URL is supplied.

## `query` (type: `string`):

Optional search text retained as run provenance.

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

Fetch each source-linked public property detail URL directly when it is exposed.

## `includeReviews` (type: `boolean`):

Retain review objects exposed in public HTML or JSON-LD.

## `maxReviews` (type: `integer`):

Maximum review objects retained per property.

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

Maximum source-backed property records to emit.

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

Maximum direct public listing pages to follow per start URL.

## `minPrice` (type: `number`):

Optional minimum monthly price filter based on the public range.

## `maxPrice` (type: `number`):

Optional maximum monthly price filter based on the public range.

## `minBedrooms` (type: `number`):

Optional minimum public bedroom range.

## `maxBedrooms` (type: `number`):

Optional maximum public bedroom range.

## `requestDelayMs` (type: `integer`):

Bounded pacing delay between direct public requests.

## `timeoutSecs` (type: `integer`):

Timeout for each direct public HTTPS request.

## Actor input object example

```json
{
  "authorizationConfirmed": false,
  "location": "chicago-il",
  "includeDetails": true,
  "includeReviews": false,
  "maxReviews": 20,
  "maxItems": 50,
  "maxPages": 5,
  "requestDelayMs": 250,
  "timeoutSecs": 45
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset containing normalized source-backed Apartments.com listings only.

## `summary` (type: `string`):

Key-value store containing the OUTPUT_SUMMARY run record.

# 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 = {
    "location": "chicago-il",
    "maxReviews": 20,
    "maxItems": 50,
    "maxPages": 5,
    "requestDelayMs": 250,
    "timeoutSecs": 45
};

// Run the Actor and wait for it to finish
const run = await client.actor("realestateapi/apartments-properties-and-details-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 = {
    "location": "chicago-il",
    "maxReviews": 20,
    "maxItems": 50,
    "maxPages": 5,
    "requestDelayMs": 250,
    "timeoutSecs": 45,
}

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

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

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

```

## CLI example

```bash
echo '{
  "location": "chicago-il",
  "maxReviews": 20,
  "maxItems": 50,
  "maxPages": 5,
  "requestDelayMs": 250,
  "timeoutSecs": 45
}' |
apify call realestateapi/apartments-properties-and-details-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,realestateapi/apartments-properties-and-details-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/WCClsNhX1ot00yDWt/builds/rxLRmdanEzVbQ9J8s/openapi.json