# Realtor Search

## Overview

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

## Description

Search Realtor.com listings from a search URL and retrieve prices, beds, baths, sqft, photos, and property metadata.

## 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/realtor/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search homes for sale in New York

```json
{
  "results": [
    {
      "photos": [
        {
          "href": "https://ap.rdcpix.com/67dd84d210896e04e1252c2c8bc52c57l-m3226683124s.jpg"
        }
      ],
      "location": {
        "address": {
          "city": "Brooklyn",
          "line": "299 Troutman St",
          "state": "NY",
          "postal_code": "11237"
        }
      },
      "permalink": "299-Troutman-St_Brooklyn_NY_11237_M99576-61733",
      "list_price": 500000,
      "description": {
        "beds": 16,
        "sqft": 6500,
        "type": "SingleFamilyResidence",
        "baths": 8,
        "lot_size": 2500
      },
      "property_id": "9957661733"
    },
    {
      "photos": [
        {
          "href": "https://ap.rdcpix.com/eac307cc2348e0014f42e489f57f5d02l-m3092249856s.jpg"
        }
      ],
      "location": {
        "address": {
          "city": "Bronx",
          "line": "D132 Edgewater Unit D",
          "state": "NY",
          "postal_code": "10465"
        }
      },
      "permalink": "D132-Edgewater-Unit-D_Bronx_NY_10465_M94332-74355",
      "list_price": 255000,
      "description": {
        "beds": 4,
        "sqft": 1200,
        "type": "SingleFamilyResidence",
        "baths": 1,
        "lot_size": null
      },
      "property_id": "9433274355"
    },
    {
      "photos": [
        {
          "href": "https://ap.rdcpix.com/77415ad2b4919799a0cb455c54eab3fcl-m2351895655s.jpg"
        }
      ],
      "location": {
        "address": {
          "city": "New York",
          "line": "2573 Frederick Douglass Blvd Apt A",
          "state": "NY",
          "postal_code": "10030"
        }
      },
      "permalink": "2573-Frederick-Douglass-Blvd-Apt-A_New-York_NY_10030_M92978-65175",
      "list_price": 275000,
      "description": {
        "beds": 2,
        "sqft": 1175,
        "type": "Apartment",
        "baths": 2.5,
        "lot_size": null
      },
      "property_id": "9297865175"
    },
    {
      "photos": [
        {
          "href": "https://ap.rdcpix.com/e5f2913192e3c223cc21e05ea213844el-m1072321830s.jpg"
        }
      ],
      "location": {
        "address": {
          "city": "Woodhaven",
          "line": "86-34 77th St",
          "state": "NY",
          "postal_code": "11421"
        }
      },
      "permalink": "8634-77th-St_Woodhaven_NY_11421_M46500-03200",
      "list_price": 603200,
      "description": {
        "beds": 6,
        "sqft": null,
        "type": "SingleFamilyResidence",
        "baths": 2,
        "lot_size": 2614
      },
      "property_id": "4650003200"
    }
  ]
}
```

## Documentation

## Overview
Extract property listings from any Realtor.com search results page. Returns structured listings with photos, address, price, beds, baths, sqft, property type, and permalinks.

## Quickstart
```
GET https://api.piloterr.com/v2/realtor/search?query=https://www.realtor.com/realestateandhomes-search/New-York_NY
```

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

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | List of property listings |
| `results[].property_id` | string | Realtor.com property ID |
| `results[].permalink` | string | Property permalink slug |
| `results[].list_price` | integer | List price in USD |
| `results[].photos` | array | Listing photos (`href`) |
| `results[].location.address.line` | string | Street address |
| `results[].location.address.city` | string | City |
| `results[].location.address.state` | string | State code |
| `results[].location.address.postal_code` | string | ZIP code |
| `results[].description.beds` | integer \| null | Bedrooms |
| `results[].description.baths` | number \| null | Bathrooms |
| `results[].description.sqft` | integer \| null | Interior sqft |
| `results[].description.lot_size` | integer \| null | Lot size |
| `results[].description.type` | string | Property type code |

## Notes
- Response is returned under `results`.
- Only full Realtor.com search URLs are accepted as `query`.
- Pass a property detail URL to the Realtor Property endpoint for full listing data.

## Main use cases
- Monitor for-sale inventory in a target city or state
- Build lead lists with price, beds, baths, and photos
- Feed property discovery pipelines for real estate analytics
- Enrich CRM records from live Realtor.com search pages