# Changelog of Apartments.com API & Scraper — US Rentals + Walk Score (`sian.agency/apartments-com-property-scraper`) Actor

- **URL**: https://apify.com/sian.agency/apartments-com-property-scraper/changelog.md
- **Full Actor documentation**: https://apify.com/sian.agency/apartments-com-property-scraper.md

## Changelog

All notable changes to **Apartments.com API & Scraper — US Rentals + Walk Score** will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

***

### \[2026-09-11]

#### 🖼️ Images

- 🖼️ **New `thumbnailUrl`.** Each row now carries a preview image, taken from the first photo on the listing, so the Output tab shows a picture per row.
- 🖼️ **The photos were always collected — now you can see them.** The full image gallery and its preview thumbnail appear in the Output tab and in every export, instead of only in the raw JSON.

### \[Unreleased] — backlog

#### 🚀 Planned (next release)

- **Autocomplete Mode** — surface apartments.com location autocomplete as a standalone search-helper output
- **Granular Enrichment Toggles** — pick walk score API only, or schools only, etc. — pay only for what you pull

***

### \[2026-07-30] — Polygon + Region-ID search

#### ✨ Added

- **🔷 By Polygon search** — draw any market boundary as a closed `lon lat, lon lat, …` ring and pull every listing inside it. Perfect for irregular submarkets, school-district shapes, or "everything between these highways" pulls.
- **🗺 By Region ID search** — target apartments.com's own canonical geographies directly by `geographyId` + `geographyType` for stable, repeatable market pulls that don't depend on free-text matching.
- **Extra Enrichment Endpoints** — parking policy, attachments, transits
- **Market rent trends** (`/rental/trends`) — investigated for this release; upstream endpoint is currently broken (proxy `CONNECT` 407 on every scope, re-verified 2026-07-10) and would need its own billable event (market-analytics shape, not per-listing) with a 14-day pricing notice. Blocked on upstream fix + human pricing sign-off, not code.

***

### \[2026-07-10]

#### 🔗 Direct lookup by URL/address, similar listings, amenities + photo gallery

- **`byListingUrl` search mode** — resolve a FULL property record directly from a single apartments.com listing URL, no search step and no need to already know the internal listing key (`/details/byurl`, resolved server-side). Not paid-only. Charges the standard per-listing-extracted event once per resolved listing.
- **`byAddress` search mode** — resolve a listing directly from a street address (`/details/byaddress`). Not paid-only. apartments.com only knows properties it has an active listing for — unlisted addresses return no data and no charge.
- **Similar listings add-on (`includeSimilar`, PAID)** — apartments.com's own comparable-listings recommendations (neighborhood, price band, bedroom count) per listing. Charged as one enrichment event per listing that actually has comps — many corporate/furnished listings have zero and are never charged. Works in every search mode, including the two new direct-lookup modes.
- **Amenities + photo gallery join the enrichment bundle** — `includeEnrichment` now fires 9 parallel fetches (was 7), adding a dedicated amenities list (`amenitiesDetail`) and a full-resolution photo gallery (`photos`, `{url,caption,width,height,type}`). The photo gallery fixes a standing gap: the classic bundle's inline `details.photos` field came back empty on every listing tested — the dedicated `/details/photos` endpoint is the reliable source.
- All three new add-ons/modes reuse the existing `property-extracted` / `enrichment-fetched` pricing events — no new pricing tier, no pricing PUT required.

#### 🔍 Known upstream finding (not shipped)

- `/details/amenities` (the dedicated amenities endpoint) returns data structurally identical to what `details.amenities` (from the existing `/details/byid` bundle call) already surfaces — only cosmetic key-naming differences. Wired anyway as instructed (`amenitiesDetail`), but flagged here as a candidate for a future cleanup (drop the duplicate call, or make it the canonical amenities source) — not code-blocking, needs a human call on the tradeoff.

***

### \[2026-07-02]

#### 💬 Renter reviews + 💵 fees & costs add-ons, and a direct listing mode

- **Renter reviews add-on (`includeReviews`, PAID)** — review title, full text, 1–5 rating, submission date, owner flag, and helpful-vote count per listing, plus the listing's total review count. Charged as one enrichment event per listing that actually has reviews — review-less listings are never charged.
- **Fees & costs add-on (`includeFees`, PAID)** — the complete fee/expense schedule (one-time expenses, custom/admin fees, and profile fees with amounts, refundability, and recurrence), the property-management company (name + direct phone), and leasing-office hours — all in a single enrichment charge per listing where data was found.
- **New `byListingKeys` search mode (PAID)** — enrich known buildings directly by listing key (e.g. `"7zg13yw"`) or full apartments.com listing URL, without re-running a search. No per-listing extraction charge in this mode — you pay only for the add-on data delivered. If no add-on toggle is selected, reviews + fees are fetched by default.
- Both add-ons also work in every existing search mode — flip them ON alongside (or instead of) the classic enrichment bundle.

***

### \[2026-06-14]

#### ⚡ Faster large-area pulls

- **High-throughput pagination** — each query now pulls up to the full per-search maximum in a single request instead of trickling listings 50 at a time. Big metros (Austin, NYC, LA) return their full result set far faster, with far fewer round-trips per run.
- **Clearer max-results UX** — the "Max results per query" cap now reflects the true per-search ceiling, so the run summary matches what's actually deliverable for a given area.

***

### \[2026-05-15]

#### 🎉 Apartments.com API & Scraper — Launch!

- **Apartments.com API (5 Search Modes)** — pull US rental listings by location, 5-digit zip, lat/lng radius, apartments.com URL, or bulk-location batch (PAID) with one consistent JSON schema
- **One-Click Enrichment Bundle** — walk score API, schools, pet policy, lease terms, rental costs, building info, and per-unit availability fetched in parallel and charged as a **single** `enrichment-fetched` event per listing
- **Built-In Market Rent KPIs** — median midpoint rent, median rent per bed, rent-distribution percentiles, and inventory tally computed per query and saved to the dataset key-value store as `marketKpis`
- **HTML KPI Report Export** — pre-rendered apartments.com data dashboard with KPI cards, rent distribution stats, and methodology saved to key-value store as `report.html` — ready to drop into client decks
- **BigInt-Safe Apartments.com Data** — `amenitiesBitmap` and other 64-bit identifiers preserved as strings so your downstream stack gets 1:1 fidelity (most scrapers silently lose precision)
- **6-Tier Auto-Scaling Pricing** — FREE → BRONZE → SILVER → GOLD → PLATINUM → DIAMOND auto-ladder; canonical-framework actor-start ($0.12 FREE → $0.012 paid) bakes in cost containment; `property-extracted` is the headline event flattening at GOLD ($0.003)
- **Pay-Per-Result** — zero charge for empty searches or failed lookups; you only pay for listings actually extracted and rows actually pushed to the dataset

#### 💎 User Benefits

- **PropTech teams** stop maintaining a fragile in-house apartments.com scraper and use a stable apartments.com API instead — save 20+ engineering hours per month
- **Multifamily underwriters** get median rent, $/bed, and inventory KPIs per zip in seconds — drop into the DCF without a single line of post-processing
- **Rental concierges** get manager contact, walk score API, pet policy, and lease terms in one call — build client shortlists in 30 minutes instead of 30 hours
- **Tenant-facing app builders** get clean structured JSON apartments.com data ready for an LLM context window — no HTML parsing needed
- **Market-intelligence agencies** white-label the HTML KPI report or pipe the dataset into a client's BI stack the same day

#### 🎯 Use Cases

- **PropTech engineer** powering a rental-search product across 50 US states with the apartments.com API as the data backbone
- **Real-estate underwriter** pulling rent-comp KPIs for 30 zip codes in one bulk-location run to sanity-check sponsor projections
- **Rental concierge** prospecting buildings in a 2-mile radius around a client's office with walk score API and pet-policy data attached
- **Academic researcher** running weekly time-series captures of the same zips to study rent growth and inventory drift
- **Conversational AI builder** feeding apartments.com data into an LLM agent that helps users "find me a 2-bed under $3000 in Brooklyn"

#### ⚖️ Compliance

- Trademark disclaimer: independent tool, not affiliated with CoStar Group, Inc.
- GDPR-aware: actor reads only publicly published apartments.com listings — no private user data extracted