# Realestate Newsletter Agent Langgraph (`gopalakrishnan/realestate-newsletter-agent-langgraph`) Actor

An autonomous Apify actor that generates comprehensive real estate market research reports by analyzing data from multiple authoritative sources.

- **URL**: https://apify.com/gopalakrishnan/realestate-newsletter-agent-langgraph.md
- **Developed by:** [Gopalakrishnan](https://apify.com/gopalakrishnan) (community)
- **Categories:** Agents, Real estate, Open source
- **Stats:** 12 total users, 1 monthly users, 0.0% runs succeeded, 2 bookmarks
- **User rating**: 1.00 out of 5 stars

## Pricing

from $20.00 / 1,000 search initializations

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Real Estate Market Research Agent

An autonomous Apify actor that generates comprehensive real estate market research reports by analyzing data from multiple authoritative sources.

### 🤖 Autonomous Capabilities

The agent operates through a series of autonomous modules, each handling specific aspects of market research:

1. **Search Agent**
   - Autonomously discovers relevant market research URLs
   - Filters and validates sources based on authority and relevance
   - Supports major real estate platforms (Zillow, Redfin, Realtor.com)

2. **Data Extraction Agent**
   - Scrapes market data from validated sources
   - Handles different page structures and data formats
   - Memory-efficient crawling with residential proxy support

3. **Market Analysis Agent**
   - Validates and normalizes price data
   - Detects high-cost markets automatically
   - Calculates key metrics with outlier detection
   - Cross-references data points for accuracy

4. **Newsletter Generation Agent**
   - Creates professional market reports using AI
   - Formats data in a consistent, readable structure
   - Provides actionable insights and recommendations
   - Includes source citations and data comparisons

### 💡 Strategic Advantages of Domain-Specific Approach

This agent focuses on real estate market research for several strategic reasons:

1. **Data Quality Assurance**
   - Real estate platforms provide structured, verifiable data sources
   - Metrics can be cross-validated across multiple authoritative sources
   - Numerical data extraction demonstrates more technical complexity than text-only scraping

2. **Showcasing Apify's Core Strengths**
   - Leverages Apify's powerful scraping capabilities for complex websites
   - Demonstrates handling of sophisticated anti-bot measures on real estate sites
   - Utilizes residential proxies to access geo-restricted market data

3. **Business Value & Market Need**
   - Real estate professionals require accurate, timely market data
   - Consumers need unbiased analysis from multiple sources
   - Investment decisions rely on comprehensive market information

4. **Technical Differentiation**
   - More challenging extraction tasks requiring precise numerical data
   - Complex validation rules and outlier detection
   - Domain-specific knowledge integration for analysis
   - Transformation of raw data into actionable business insights

While general newsletters can be created with many platforms, real estate market analysis specifically leverages Apify's unique advantages in structured data extraction from complex sources.

### 💰 Pay-Per-Event Pricing

The actor uses a transparent pay-per-event pricing model:

- Search initialization: $0.02
- URL processing: $0.02 per valid URL
- Data extraction: $0.02 per source
- Market analysis: $0.02 per source
- Newsletter generation: $0.50

Total cost per run: $0.72 - $0.80 (depending on number of sources)

### 🚀 Input Parameters

```json
{
    "location": "City, State",
    "debug": false
}
```

### 📊 Output Format

```json
{
    "location": "City, State",
    "filtered_urls": {
        "zillow": "url",
        "redfin": "url",
        "realtor": "url"
    },
    "market_data": {
        // Raw extracted data from each source
    },
    "analysis": {
        "metrics": {
            // Processed market metrics
        },
        "source_urls": {
            // Source attribution
        }
    },
    "newsletter": "Formatted markdown report"
}
```

### 🔧 Technical Requirements

- Python 3.13+
- OpenAI API key
- Apify Platform account
- Residential proxy access (provided by Apify)

### 🛠️ Environment Variables

Required:

- `APIFY_TOKEN`: Your Apify API token
- `OPENAI_API_KEY`: Your OpenAI API key

### 📝 Newsletter Format

The generated newsletter includes:

- Executive Summary
- Market Overview
- Market Data Comparison
- Price Analysis
- Market Activity
- Market Forecast
- Recommendations
- Additional Resources

### 🏗️ Architecture

The actor is built with a modular architecture:

```
src/
├── agents/
│   ├── search_agent.py
│   ├── extraction_agent.py
│   ├── analysis_agent.py
│   └── newsletter_agent.py
├── models/
│   └── schemas.py
├── utils/
│   └── url_patterns.py
└── main.py
```

### 📈 Validation & Error Handling

- Price validation ranges adjust automatically for high-cost markets
- Outlier detection in price and market metrics
- Comprehensive error logging and state tracking
- Graceful handling of missing or invalid data

### 🔄 Continuous Updates

The agent automatically:

- Updates search patterns for current year
- Validates data freshness
- Adapts to source website changes
- Handles new market conditions

### 📚 Usage Example

```python
from apify_client import ApifyClient

## Initialize the client
client = ApifyClient('YOUR_API_TOKEN')

## Run the actor
run = client.actor('username/real-estate-market-research').call(run_input={
    'location': 'San Jose, CA'
})

## Get results
output = client.dataset(run['defaultDatasetId']).list_items().items[0]
print(output['newsletter'])
```

### 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

### 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

# Actor input Schema

## `location` (type: `string`):

City and State (e.g. 'San Jose, CA')

## `openaiApiKey` (type: `string`):

Your OpenAI API key

## `debug` (type: `boolean`):

Enable debug logging

## Actor input object example

```json
{
  "debug": false
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("gopalakrishnan/realestate-newsletter-agent-langgraph").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("gopalakrishnan/realestate-newsletter-agent-langgraph").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call gopalakrishnan/realestate-newsletter-agent-langgraph --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gopalakrishnan/realestate-newsletter-agent-langgraph"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/7s2mO05eKc0GG1nKr/builds/uLEeCYu0iLK2RdFub/openapi.json