===============
LIBRARY RULES
===============
From library maintainers:
- Always authenticate requests with API key in headers
- Use PropGPT for natural language property searches with plain English queries
- Use bulk operations for multiple property lookups (up to 1,000 properties)
- Leverage compound queries for complex Boolean search logic
- Use ids_only mode for credit optimization with large datasets
- Implement rate limiting to respect API quotas and model-specific limits
- Cache property data appropriately - demographics annually, boundaries indefinitely
- Use AutoComplete API for free unlimited address suggestions
- Implement saved searches for ongoing property monitoring
- Handle pagination with cursor-based pagination for large datasets
- Validate addresses with Address Verification API before searches
- Use appropriate search modes: count for totals, summary for analytics
- Leverage mapping APIs for boundary visualization and area analysis
- Check API version compatibility before implementation - v3 will introduce breaking changes
- Use version-specific documentation and examples for accurate implementation

# RealEstateAPI

RealEstateAPI is a comprehensive real estate data platform that provides developers with access to nationwide property records, MLS listings, property valuations, skip tracing, and address verification services. The API enables building powerful real estate applications with features like natural language property search (PropGPT), detailed property information including mortgages and sales history, comparable property analysis, and contact information lookup for property owners.

The platform offers a RESTful API with consistent JSON responses, supporting over 100 search filters for property queries, bulk processing capabilities, and webhook integrations. All endpoints require API key authentication via the `x-api-key` header, with some specialized endpoints like PropGPT requiring additional authentication. The API supports pagination, polygon-based geographic searches, and provides both individual and bulk endpoints for high-throughput applications.

## Authentication

All RealEstateAPI v2 endpoints require an API key passed as an HTTP header. The API validates the key on every request and controls endpoint access via scopes.

```bash
# Standard authentication with x-api-key header
curl -X POST https://api.realestateapi.com/v2/PropertySearch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city": "Austin", "state": "TX", "size": 10}'

# PropGPT requires dual authentication (RealEstateAPI + OpenAI keys)
curl -X POST https://api.realestateapi.com/v2/PropGPT \
  -H "x-api-key: YOUR_REAPI_KEY" \
  -H "x-openai-key: YOUR_OPENAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "3 bed homes in Austin TX under 500k", "model": "gpt-4o-mini"}'
```

## Property Search API

Search for properties with over 100 filter parameters including location, property characteristics, ownership status, equity, foreclosure status, and MLS activity. Supports pagination with `size` and `resultIndex` parameters.

```bash
# Basic property search by location and filters
curl -X POST https://api.realestateapi.com/v2/PropertySearch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "Houston",
    "state": "TX",
    "size": 50,
    "bedrooms_min": 3,
    "bedrooms_max": 4,
    "absentee_owner": true,
    "equity": true,
    "estimated_value_min": 200000,
    "estimated_value_max": 500000
  }'

# Response includes property array with key fields
# {
#   "statusCode": 200,
#   "resultCount": 847,
#   "data": [{
#     "id": "253175355",
#     "address": {"address": "123 Main St", "city": "Houston", "state": "TX", "zip": "77001"},
#     "bedrooms": 3,
#     "bathrooms": 2,
#     "squareFeet": 1850,
#     "estimatedValue": 425000,
#     "equityPercent": 38,
#     "absenteeOwner": true,
#     "owner1FirstName": "John",
#     "owner1LastName": "Smith"
#   }]
# }
```

## Property Search with Compound Queries

Use nested `and`/`or` clauses for complex Boolean logic when simple flat queries don't meet your needs. This enables highly specific property targeting.

```javascript
const response = await fetch('https://api.realestateapi.com/v2/PropertySearch', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    size: 50,
    city: "Austin",
    state: "TX",
    and: [
      // All conditions in this block must be satisfied
      {
        and: [
          { absentee_owner: true },
          { bedrooms_min: 3, bedrooms_max: 5 },
          { corporate_owned: true }
        ]
      },
      // At least one condition in this block must be satisfied
      {
        or: [
          { property_type: "LAND" },
          { property_type: "MOBILE" }
        ]
      }
    ]
  })
});

const result = await response.json();
console.log(`Found ${result.resultCount} matching properties`);
```

## Property Search with Polygon

Search within custom geographic boundaries using latitude/longitude coordinates. Supports single polygons and multi-polygon searches for complex geographic areas.

```bash
# Single polygon search
curl -X POST https://api.realestateapi.com/v2/PropertySearch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 100,
    "polygon": [
      {"lon": "-86.32762", "lat": "35.42300"},
      {"lon": "-86.43359", "lat": "35.19184"},
      {"lon": "-86.05720", "lat": "35.15490"},
      {"lon": "-86.00921", "lat": "35.45088"},
      {"lon": "-86.32762", "lat": "35.42300"}
    ],
    "bedrooms_min": 2,
    "equity": true
  }'

# Multi-polygon search
curl -X POST https://api.realestateapi.com/v2/PropertySearch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 100,
    "multi_polygon": [
      [
        {"lon": "-86.32762", "lat": "35.42300"},
        {"lon": "-86.43359", "lat": "35.19184"},
        {"lon": "-86.05720", "lat": "35.15490"},
        {"lon": "-86.32762", "lat": "35.42300"}
      ],
      [
        {"lon": "-87.10000", "lat": "35.50000"},
        {"lon": "-87.20000", "lat": "35.40000"},
        {"lon": "-87.05000", "lat": "35.35000"},
        {"lon": "-87.10000", "lat": "35.50000"}
      ]
    ]
  }'
```

## Property Detail API

Retrieve comprehensive property information by REAPI property ID or address, including ownership details, mortgage history, sales history, tax information, school data, demographics, and comparable properties.

```python
import requests

# Get full property details by ID
response = requests.post(
    'https://api.realestateapi.com/v2/PropertyDetail',
    headers={'x-api-key': 'YOUR_API_KEY'},
    json={'id': 8195564}
)

# Or by address
response = requests.post(
    'https://api.realestateapi.com/v2/PropertyDetail',
    headers={'x-api-key': 'YOUR_API_KEY'},
    json={'address': '1433 Canyon Rd, Santa Fe, NM 87501'}
)

data = response.json()['data']

# Access property sections
print(f"Owner: {data['ownerInfo']['owner1FullName']}")
print(f"Estimated Value: ${data['estimatedValue']:,}")
print(f"Equity: ${data['estimatedEquity']:,} ({data['equityPercent']}%)")
print(f"Year Built: {data['propertyInfo']['yearBuilt']}")
print(f"Bedrooms: {data['propertyInfo']['bedrooms']}, Baths: {data['propertyInfo']['bathrooms']}")

# Mortgage history
for mortgage in data.get('mortgageHistory', []):
    print(f"Mortgage: ${mortgage['amount']:,} from {mortgage['lenderName']} ({mortgage['documentDate']})")

# Sales history
for sale in data.get('saleHistory', []):
    print(f"Sale: ${sale['saleAmount']:,} on {sale['saleDate']} - {sale['transactionType']}")
```

## Property Detail Bulk API

Fetch detailed property information for up to 1,000 property IDs in a single request. Ideal for enriching property lists from search results.

```javascript
const propertyIds = [8195564, 253175355, 487291023, 41794029];

const response = await fetch('https://api.realestateapi.com/v2/PropertyDetailBulk', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ ids: propertyIds })
});

const result = await response.json();

result.data.forEach(property => {
  console.log(`${property.propertyInfo.address.label}`);
  console.log(`  Value: $${property.estimatedValue?.toLocaleString()}`);
  console.log(`  Owner: ${property.ownerInfo?.owner1FullName}`);
  console.log(`  Mortgages: ${property.currentMortgages?.length || 0}`);
});
```

## Property Mapping API

Get latitude, longitude, and property IDs for map pin rendering. Supports up to 10,000 results per request with minimal data transfer.

```javascript
const response = await fetch('https://api.realestateapi.com/v2/PropertyMapping', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    city: 'Austin',
    state: 'TX',
    bedrooms_min: 3,
    absentee_owner: true,
    size: 5000
  })
});

const { data, resultCount } = await response.json();
console.log(`Found ${resultCount} properties for mapping`);

// Render pins on your map application
data.forEach(pin => {
  map.addMarker({
    lat: pin.latitude,
    lng: pin.longitude,
    id: pin.id  // Use this ID to fetch full details on click
  });
});
```

## PropGPT API (Natural Language Search)

Translate plain English queries into structured property searches using OpenAI GPT models. Requires both RealEstateAPI and OpenAI API keys.

```python
import requests

response = requests.post(
    'https://api.realestateapi.com/v2/PropGPT',
    headers={
        'x-api-key': 'YOUR_REAPI_KEY',
        'x-openai-key': 'YOUR_OPENAI_KEY'
    },
    json={
        'query': 'Find vacant absentee-owned properties in Phoenix AZ with high equity built before 2000',
        'model': 'gpt-4o-mini',
        'size': 20
    }
)

result = response.json()['data']

# Inspect how GPT interpreted your query
print(f"Generated search parameters: {result['searchInput']}")
print(f"GPT execution time: {result['propGPTExecutionTimeMS']}ms")
print(f"Search execution time: {result['searchExecutionTimeMS']}ms")
print(f"Found {result['resultCount']} properties")

for prop in result['data']:
    addr = prop['address']
    print(f"  {prop['id']}: {addr['address']}, {addr['city']}, {addr['state']}")
```

## SkipTrace API v2

Retrieve contact information (phones, emails, social profiles) and demographic data for property owners by address, mailing address, phone, email, or name lookup. Includes demographic filters for age, gender, ethnicity, marital status, and occupation.

```bash
# Skip trace by property address with demographic filters
curl -X POST https://api.realestateapi.com/v2/SkipTrace \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "6806 19th Rd N",
    "city": "Arlington",
    "state": "VA",
    "zip": "22205",
    "age_range_min": 30,
    "age_range_max": 65,
    "match_requirements": {
      "phones": true,
      "emails": true,
      "operator": "or"
    }
  }'

# Skip trace by phone number
curl -X POST https://api.realestateapi.com/v2/SkipTrace \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "7035551234"}'

# Skip trace by email
curl -X POST https://api.realestateapi.com/v2/SkipTrace \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "contact@example.com"}'

# Skip trace with occupation filter (array of occupation codes)
curl -X POST https://api.realestateapi.com/v2/SkipTrace \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "occupation_code": [23, 36, 38]
  }'
```

## Bulk SkipTrace API

Process up to 1,000 skip trace requests in a single API call with webhook delivery. Results are delivered asynchronously to your webhook URL.

```javascript
const response = await fetch('https://api.realestateapi.com/v2/SkipTraceBatch', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    webhook_url: 'https://yourserver.com/api/skiptrace-results',
    webcomplete_url: 'https://yourserver.com/api/skiptrace-complete',
    requests: [
      {
        key: 'record-001',
        mail_address: '123 Main St',
        mail_city: 'Austin',
        mail_state: 'TX',
        mail_zip: '78701',
        first_name: 'John',
        last_name: 'Smith'
      },
      {
        key: 'record-002',
        mail_address: '456 Oak Ave',
        mail_city: 'Houston',
        mail_state: 'TX',
        mail_zip: '77001'
      }
      // ... up to 1,000 records
    ]
  })
});

const result = await response.json();
console.log(`Batch ID: ${result.batchId}`);
console.log(`Processing ${result.receiveCount} records`);

// Results will be POSTed to your webhook_url for each record
// Completion notification sent to webcomplete_url when batch finishes
```

## Property Comps API

Find comparable recently-sold properties for valuation analysis. Returns properties with similar size, age, and location that sold recently.

```python
import requests

response = requests.post(
    'https://api.realestateapi.com/v2/PropertyComps',
    headers={'x-api-key': 'YOUR_API_KEY'},
    json={'address': '123 Main St, Austin TX 78701'}
)

result = response.json()
subject = result['data']['subject']
comps = result['data']['comps']

print(f"Subject Property: {subject['address']}")
print(f"  AVM Estimate: ${subject['estimatedValue']:,}")
print(f"  Beds/Baths: {subject['bedrooms']}/{subject['bathrooms']}")
print(f"  Sq Ft: {subject['squareFeet']:,}")

print(f"\nComparable Properties ({len(comps)} found):")
for i, comp in enumerate(comps, 1):
    print(f"  {i}. {comp['squareFeet']:,} sqft, {comp['bedrooms']} bed/{comp['bathrooms']} bath")
    print(f"     Sold: ${comp.get('lastSaleAmount', 0):,} on {comp.get('lastSaleDate', 'N/A')}")
    print(f"     AVM: ${comp['estimatedValue']:,}")
```

## Address Verification API

Verify and standardize up to 100 addresses per request. Returns REAPI property IDs for verified addresses, enabling data enrichment workflows.

```javascript
const response = await fetch('https://api.realestateapi.com/v2/AddressVerification', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    addresses: [
      {
        key: 'addr-001',
        street: '123 Main Street',
        city: 'Austin',
        state: 'TX',
        zip: '78701'
      },
      {
        key: 'addr-002',
        address: '456 Oak Ave, Houston, TX 77001'  // Full address string also accepted
      },
      {
        key: 'addr-003',
        street: '789 Pine Blvd',
        zip: '90210'  // City/state not required when ZIP provided
      }
    ]
  })
});

const result = await response.json();

result.data.forEach(addr => {
  if (addr.match) {
    console.log(`[${addr.key}] Verified: ${addr.address.label}`);
    console.log(`  Property ID: ${addr.id}`);  // Use with PropertyDetail API
    console.log(`  Confidence: ${addr.confidence}`);
  } else {
    console.log(`[${addr.key}] Not verified: ${addr.error || 'No match found'}`);
  }
});
```

## AutoComplete API

Machine learning-powered address autocomplete for search bars and input fields. Free unlimited usage on all plan tiers.

```bash
# Full address autocomplete
curl -X POST https://api.realestateapi.com/v2/AutoComplete \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "123 Main St, Aus",
    "searchType": "fullAddress"
  }'

# City/State completion
curl -X POST https://api.realestateapi.com/v2/AutoComplete \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "San Fr",
    "searchType": "cityState"
  }'

# County completion
curl -X POST https://api.realestateapi.com/v2/AutoComplete \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "Orange",
    "searchType": "county"
  }'

# APN (Assessor Parcel Number) completion
curl -X POST https://api.realestateapi.com/v2/AutoComplete \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "011279",
    "searchType": "apn",
    "state": "TX"
  }'
```

## Property Boundary API

Retrieve property parcel boundaries in GeoJSON format for mapping applications. Returns shape files for individual properties or search results.

```python
import requests

# Get parcel boundary by property ID
response = requests.post(
    'https://api.realestateapi.com/v2/PropertyParcel',
    headers={'x-api-key': 'YOUR_API_KEY'},
    json={'id': 8195564}
)

result = response.json()
geojson = result['data']['geometry']

# GeoJSON can be rendered directly on map libraries like Leaflet or Mapbox
print(f"Geometry type: {geojson['type']}")
print(f"Coordinates: {geojson['coordinates']}")

# Get boundary by address
response = requests.post(
    'https://api.realestateapi.com/v2/PropertyParcel',
    headers={'x-api-key': 'YOUR_API_KEY'},
    json={'address': '1433 Canyon Rd, Santa Fe, NM 87501'}
)
```

## MLS Search API

Search active and historical MLS listings with filters for price, property type, listing status, days on market, and agent information.

```bash
curl -X POST https://api.realestateapi.com/v2/MLSSearch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "Austin",
    "state": "TX",
    "size": 50,
    "status": "Active",
    "price_min": 300000,
    "price_max": 600000,
    "bedrooms_min": 3,
    "property_type": "single_family"
  }'

# Response includes MLS-specific fields
# {
#   "statusCode": 200,
#   "resultCount": 234,
#   "data": [{
#     "mlsNumber": "12345678",
#     "price": 450000,
#     "status": "Active",
#     "daysOnMarket": 15,
#     "listingDate": "2024-01-15",
#     "agentName": "Jane Realtor",
#     "agentPhone": "5125551234",
#     "agentOffice": "ABC Realty",
#     "photos": ["https://..."],
#     "propertyInfo": {...}
#   }]
# }
```

## Lender-Grade AVM API

Professional-grade automated valuation model using statistical modeling, recent sales data, and market analysis for accurate property valuations.

```python
import requests

response = requests.post(
    'https://api.realestateapi.com/v2/PropertyAvm',
    headers={'x-api-key': 'YOUR_API_KEY'},
    json={'address': '123 Main St, Austin, TX 78701'}
)

result = response.json()['data']

print(f"Estimated Value: ${result['estimatedValue']:,}")
print(f"Value Range: ${result['valueLow']:,} - ${result['valueHigh']:,}")
print(f"Confidence Score: {result['confidence']}")
print(f"Forecast 12mo: ${result.get('forecast12Month', 'N/A')}")
```

## Bulk AVM API

Get property valuations for up to 100 properties in a single request.

```javascript
const response = await fetch('https://api.realestateapi.com/v2/PropertyAvmBulk', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    properties: [
      { id: 8195564 },
      { address: '456 Oak Ave, Houston, TX 77001' },
      { id: 253175355 }
    ]
  })
});

const result = await response.json();
result.data.forEach(prop => {
  console.log(`${prop.address}: $${prop.estimatedValue?.toLocaleString()}`);
});
```

## Response Envelope

All RealEstateAPI v2 endpoints return responses in a consistent envelope format with status codes, messages, and data payloads.

```javascript
// Success response structure
{
  "statusCode": 200,
  "statusMessage": "OK",
  "resultCount": 42,      // Total matching records
  "resultIndex": 0,       // Pagination offset
  "data": [...]           // Endpoint-specific payload
}

// Error response structure
{
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "error": "Validation error message"
}

// No results (not an error)
{
  "statusCode": 200,
  "statusMessage": "OK",
  "resultCount": 0,
  "data": []
}

// Rate limit response
{
  "statusCode": 429,
  "statusMessage": "Too Many Requests",
  "error": "Rate limit exceeded"
}
```

RealEstateAPI is designed for real estate investors, agents, lenders, and proptech developers who need access to comprehensive property data at scale. Common use cases include building property lists for marketing campaigns, identifying investment opportunities through equity and ownership filters, performing due diligence with detailed property records, finding property owner contact information for outreach, creating interactive property maps, and generating comparable sales reports for valuations.

The API integrates seamlessly with CRMs like Salesforce and HubSpot through Zapier, supports webhook-based workflows for asynchronous processing, and provides bulk endpoints for high-volume data needs. The consistent REST architecture and JSON responses make it straightforward to integrate into any programming language or platform. For map-based applications, the Property Mapping and Property Boundary APIs provide optimized endpoints for rendering thousands of property pins and parcel boundaries without downloading full property records.