# Apartments Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/apartments/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/apartments-search |

## Description

Search Apartments.com rentals from a full city or browse URL and retrieve prices, photos, addresses, phone numbers, and pagination via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/apartments/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search rentals in New York, page 3

```json
{
  "results": [
    {
      "id": "p6b4mes",
      "url": "https://www.apartments.com/141-e-33rd-st-new-york-ny-unit-si-fl16-id43/p6b4mes/",
      "image": "https://images1.apartments.com/i2/SF9HSqkGqXN0cjmR2cUNbgLuxyXklZLpKYtInYim0XI/118/141-e-33rd-st-unit-si-fl16-id43-new-york-ny-building-photo.jpg?p=1",
      "phone": "8555266751",
      "title": "141 E 33rd St Unit SI FL16-ID43",
      "address": "141 E 33rd St, New York, NY 10016",
      "pricing": [
        {
          "beds": "2 Beds",
          "price": "$7,210"
        }
      ],
      "has_video": false,
      "min_price": 7210,
      "image_count": 23,
      "country_code": "US",
      "property_type": "Apartment for Rent",
      "street_address": "141 E 33rd St",
      "has_virtual_tour": true
    },
    {
      "id": "kkt0hfb",
      "url": "https://www.apartments.com/53-park-pl-new-york-ny-unit-si-fl3-id53/kkt0hfb/",
      "image": "https://images1.apartments.com/i2/6wscRtCcX-3nE67ze4o41rAW9_6LCo0nJX22IYicrAk/118/53-park-pl-unit-si-fl3-id53-new-york-ny-building-photo.jpg?p=1",
      "phone": "8555289504",
      "title": "53 Park Pl Unit SI FL3-ID53",
      "address": "53 Park Pl, New York, NY 10007",
      "pricing": [
        {
          "beds": "Studio",
          "price": "$5,110"
        }
      ],
      "has_video": false,
      "min_price": 5110,
      "image_count": 28,
      "country_code": "US",
      "property_type": "Apartment for Rent",
      "street_address": "53 Park Pl",
      "has_virtual_tour": true
    },
    {
      "id": "khk0kyc",
      "url": "https://www.apartments.com/53-park-pl-new-york-ny-unit-si-fl10-id54/khk0kyc/",
      "image": "https://images1.apartments.com/i2/P4YtFr_qFvkB4rsy5m33Qw2UUAu-hNz4xmlBmvbum8I/118/53-park-pl-unit-si-fl10-id54-new-york-ny-building-photo.jpg?p=1",
      "phone": "5512272189",
      "title": "53 Park Pl Unit SI FL10-ID54",
      "address": "53 Park Pl, New York, NY 10007",
      "pricing": [
        {
          "beds": "1 Bed",
          "price": "$7,190"
        }
      ],
      "has_video": false,
      "min_price": 7190,
      "image_count": 31,
      "country_code": "US",
      "property_type": "Apartment for Rent",
      "street_address": "53 Park Pl",
      "has_virtual_tour": true
    }
  ],
  "pagination": {
    "current": 3,
    "next_url": "https://www.apartments.com/new-york-ny/4/",
    "total_count": 7775,
    "has_next_page": true
  }
}
```

## Documentation

## Overview
Extract rental listing cards from any Apartments.com search or city browse page. Returns structured results with address, pricing tiers, photos, phone, property type, and pagination metadata.

Apartments.com search pages are JavaScript single-page applications. Listing cards load dynamically after the initial HTML shell. A plain HTTP request returns an empty page skeleton. Piloterr uses **website rendering** to execute JavaScript, wait for listing cards to render, and extract structured JSON from the live DOM.

## Quickstart
```
GET https://api.piloterr.com/v2/apartments/search?query=https://www.apartments.com/new-york-ny/3
```

Copy the full URL from apartments.com. Increment the page number in the path for pagination (`/new-york-ny/4/`).

## Supported URL formats
| Format | Example |
|---|---|
| City search page 1 | `https://www.apartments.com/new-york-ny/` |
| City search page N | `https://www.apartments.com/new-york-ny/3` |

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Full Apartments.com city or search URL |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | Rental listing cards |
| `results[].id` | string | Apartments.com listing ID |
| `results[].url` | string | Property detail URL |
| `results[].title` | string | Listing title |
| `results[].address` | string | Full formatted address |
| `results[].street_address` | string | Street line |
| `results[].phone` | string \| null | Contact phone |
| `results[].image` | string \| null | Main thumbnail URL |
| `results[].image_count` | integer \| null | Number of photos |
| `results[].property_type` | string \| null | e.g. `Apartment for Rent` |
| `results[].country_code` | string \| null | ISO country code |
| `results[].min_price` | integer \| null | Lowest listed price in USD |
| `results[].pricing` | array | Bed/price tiers (`beds`, `price`) |
| `results[].has_video` | boolean | Whether a video tour exists |
| `results[].has_virtual_tour` | boolean | Whether a virtual tour exists |
| `pagination.current` | integer | Current page number |
| `pagination.next_url` | string \| null | Next page URL |
| `pagination.total_count` | integer | Total matching listings |
| `pagination.has_next_page` | boolean | Whether a next page exists |

## Notes
- Targets **apartments.com** (US rental marketplace).
- Page number is encoded in the URL path, not a query parameter.
- `pricing` may contain multiple bed/price combinations per building.
- Pass `results[].url` to **Apartments Property** for amenities, gallery, description, and square footage.

## Main use cases
- Monitor rental inventory and pricing across US cities
- Build apartment lead lists with phone, address, and min price
- Feed proptech analytics pipelines with live market data
- Paginate through Apartments.com search result pages