# HotPads Rental Search API Documentation

Search rental listings on HotPads for one area: city, zip code, state or neighborhood slug. Each result is one building or house with its name, url, address, location, rent range in USD, beds, baths, square feet, available unit count, price drop count, special offer, labels, photos, and listed and updated dates (ISO 8601, UTC). Filter by property type, bedrooms and rent. Pages hold 40 results; use total_pages and has_more to page. A valid area without matching listings is a successful empty result.

- **Documentation:** [https://scrappa.co/docs/hotpads-api/hotpads_search](https://scrappa.co/docs/hotpads-api/hotpads_search)
- **API group:** HotPads API
- **Endpoint:** `GET https://scrappa.co/api/hotpads/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `area` | string | Yes | HotPads area slug: city and state such as albuquerque-nm, a zip code such as 60607, a state such as il, or a neighborhood such as river-west-chicago-il. Example: albuquerque-nm. |
| `type` | string | No | Property type: apartments, houses, condos or townhomes. Defaults to apartments. |
| `beds` | integer | No | Number of bedrooms, 0 to 5. Use 0 for studios. Works with the apartments and houses types only. |
| `min_price` | integer | No | Minimum monthly rent in USD, 0 to 100000. |
| `max_price` | integer | No | Maximum monthly rent in USD, at least min_price. |
| `page` | integer | No | Page number, 1 to 100. Defaults to 1. Each page holds up to 40 results. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/hotpads/search?area=albuquerque-nm&type=apartments"
```

## Example response

```json
{
    "success": true,
    "data": {
        "area": {
            "title": "Albuquerque, NM Apartments for Rent",
            "url": "https://hotpads.com/albuquerque-nm/apartments-for-rent"
        },
        "results": [
            {
                "id": "24fd5j2",
                "name": "Allaso Vineyards",
                "url": "https://hotpads.com/allaso-vineyards-albuquerque-nm-87122-24fd5j2/pad",
                "listing_id": "2c8mre655n0z6",
                "property_type": "large",
                "listing_type": "rental",
                "address": {
                    "street": "8901 Holly Ave NE",
                    "city": "Albuquerque",
                    "state": "NM",
                    "zip": "87122"
                },
                "location": {
                    "latitude": 35.17594813075956,
                    "longitude": -106.54412806034088
                },
                "price": {
                    "min": 1677,
                    "max": 2395,
                    "currency": "USD"
                },
                "beds": {
                    "min": 1,
                    "max": 2
                },
                "baths": {
                    "min": 1,
                    "max": 2
                },
                "sqft": {
                    "min": 761,
                    "max": 1154
                },
                "unit_count": 8,
                "price_drop_count": 6,
                "special_offer": "2 Weeks Free",
                "labels": [
                    "New Today",
                    "2 Weeks Free",
                    "Price Drop"
                ],
                "photos": [
                    "https://photos.zillowstatic.com/fp/31fd1c7864172098f9c6095072b18a94-rentals_large_1200_1200.webp",
                    "https://photos.zillowstatic.com/fp/d1508d9e73bec2e49979cfd8a4919c67-rentals_large_1200_1200.webp",
                    "https://photos.zillowstatic.com/fp/d7d5695ea5d28dcc3454d94279690c8f-rentals_large_1200_1200.webp"
                ],
                "listed_at": "2024-06-20T19:46:59Z",
                "updated_at": "2026-10-14T20:54:38Z"
            },
            {
                "id": "24ujecn",
                "name": "Allaso Olivine",
                "url": "https://hotpads.com/allaso-olivine-albuquerque-nm-87113-24ujecn/pad",
                "listing_id": "4f522xwhsm7ad",
                "property_type": "large",
                "listing_type": "rental",
                "address": {
                    "street": "6925 Alameda Blvd NE",
                    "city": "Albuquerque",
                    "state": "NM",
                    "zip": "87113"
                },
                "location": {
                    "latitude": 35.185219271148405,
                    "longitude": -106.56940519809723
                },
                "price": {
                    "min": 1499,
                    "max": 2125,
                    "currency": "USD"
                },
                "beds": {
                    "min": 0,
                    "max": 2
                },
                "baths": {
                    "min": 1,
                    "max": 2
                },
                "sqft": {
                    "min": 643,
                    "max": 1143
                },
                "unit_count": 6,
                "price_drop_count": 6,
                "special_offer": "$$500 Off",
                "labels": [
                    "$$500 Off",
                    "Price Drop"
                ],
                "photos": [
                    "https://photos.zillowstatic.com/fp/5616333195e43fb534575d18c588aba2-rentals_large_1200_1200.webp",
                    "https://photos.zillowstatic.com/fp/4a61dd6ef988234d0ea26000f70f775f-rentals_large_1200_1200.webp",
                    "https://photos.zillowstatic.com/fp/9576ee227e694714c8c9c418049b637d-rentals_large_1200_1200.webp"
                ],
                "listed_at": "2025-08-29T20:47:01Z",
                "updated_at": "2026-10-14T20:55:14Z"
            }
        ],
        "page": 1,
        "per_page": 40,
        "total_pages": 30,
        "total_results": 4453,
        "has_more": true
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A required query parameter is missing or invalid. This response is not billable. |
| 404 | Resource Not Found | The requested HotPads area does not exist. This response is not billable. |
| 503 | Upstream Unavailable | HotPads blocked the request on every exit, could not be reached, or answered with a page that no longer matches the documented contract (code UPSTREAM_BLOCKED, UPSTREAM_UNAVAILABLE or PARSER_DRIFT). This response is not billable. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)