# MLS by HansonXyz - User Documentation

## Overview

This plugin syncs property listing data from MLS Grid (NorthStar MLS) into your WordPress database, making it available for use by themes and other plugins.

## Installation

1. Upload the `mls-by-hansonxyz` folder to `/wp-content/plugins/`
2. Activate the plugin through the WordPress admin
3. Configure API credentials (see below)
4. Run initial sync

## Configuration

### API Credentials

Add to your `wp-config.php`:

```php
define('MLSGRID_API_URL', 'https://api.mlsgrid.com/v2');
define('MLSGRID_ACCESS_TOKEN', 'your-access-token-here');
```

Alternatively, configure via Settings > MLS Settings in WordPress admin.

### Settings

Navigate to **Settings > MLS Settings** to configure:

- **Originating System**: MLS identifier (default: `northstar`)
- **Auto Sync**: Enable automatic background sync
- **Sync Interval**: How often to sync (30min to daily)
- **Sync Media**: Whether to download listing photos

## Running Sync

### Via Admin Panel

1. Go to Settings > MLS Settings
2. Click "Run Incremental Sync" or "Run Full Sync"
3. Wait for completion

### Via WP-CLI

```bash
# Test connection first
wp mls test connection
wp mls test auth

# Run initial full sync
wp mls sync full

# Run incremental updates
wp mls sync incremental

# Download pending media
wp mls sync media
```

### Via Cron

Add to your system crontab for scheduled sync:

```bash
# Run incremental sync every hour
0 * * * * cd /var/www/html && wp mls sync incremental --allow-root
```

## Checking Status

### Via Admin

Settings > MLS Settings shows:
- Database statistics (property counts by status)
- Last sync time and results
- Rate limit usage

### Via CLI

```bash
# Full status
wp mls status

# Just rate limits
wp mls status rate-limits

# Database statistics
wp mls stats
```

## Using the Data

### For Theme Developers

The plugin provides global helper functions:

```php
// Get active properties in a city
$properties = mls_get_properties([
    'status' => 'Active',
    'city' => 'Albert Lea',
    'limit' => 20,
]);

foreach ($properties as $property) {
    echo $property->list_price;
    echo $property->bedrooms_total;
    echo $property->city;
}

// Get a single property
$property = mls_get_property('NST123456');

// Get property images
$media = mls_get_property_media($property->listing_key);
$primary_image = mls_get_property_image($property->listing_key);

// Get cities with active listings
$cities = mls_get_cities('Active');

// Check if data is available
if (mls_is_available()) {
    // Show property search
}
```

### Query Parameters

`mls_get_properties()` accepts these filters:

| Parameter | Type | Description |
|-----------|------|-------------|
| status | string | Active, Pending, Closed |
| property_type | string | Residential, Land, etc. |
| city | string | City name |
| county | string | County name |
| postal_code | string | ZIP code |
| min_price | int | Minimum price |
| max_price | int | Maximum price |
| min_beds | int | Minimum bedrooms |
| max_beds | int | Maximum bedrooms |
| min_baths | int | Minimum bathrooms |
| min_sqft | int | Minimum square feet |
| max_sqft | int | Maximum square feet |
| search | string | Search address/remarks |
| limit | int | Results per page |
| offset | int | Pagination offset |
| orderby | string | Sort field |
| order | string | ASC or DESC |
| include_media | bool | Include media array |

### Property Object Fields

Each property object includes:

```php
$property->listing_key       // Unique ID
$property->listing_id        // MLS number
$property->list_price        // Price
$property->standard_status   // Active, Pending, Closed
$property->street_number
$property->street_name
$property->street_suffix
$property->city
$property->state_or_province
$property->postal_code
$property->county
$property->latitude
$property->longitude
$property->property_type
$property->property_sub_type
$property->bedrooms_total
$property->bathrooms_total
$property->living_area       // Square feet
$property->lot_size_area
$property->year_built
$property->garage_spaces
$property->public_remarks    // Description
$property->directions
$property->list_office_name
$property->photos_count
$property->days_on_market
$property->modification_timestamp
```

## Media Storage

Downloaded images are stored in:
```
wp-content/uploads/mls-listings/{prefix}/{listing_key}/
```

Images are named by order: `1.jpg`, `2.jpg`, etc.

Access via:
```php
$media = mls_get_property_media($listing_key);
foreach ($media as $image) {
    echo '<img src="' . esc_url($image->local_url) . '">';
}
```

## Troubleshooting

### Connection Failed

1. Verify API token is correct in wp-config.php
2. Check that MLSGRID_API_URL is set
3. Run `wp mls test connection` for details

### No Data After Sync

1. Check `wp mls status` for errors
2. Review rate limits - may need to wait
3. Check WordPress debug log for API errors

### Media Not Downloading

1. Verify `sync_media` is enabled in settings
2. Check upload directory is writable
3. Run `wp mls sync media` manually

### Rate Limit Exceeded

The plugin automatically waits when approaching limits. If suspended:
1. Wait for the rate limit window to reset
2. Reduce sync frequency
3. Contact MLS Grid support if persistent

### Clearing Data

To start fresh:
```bash
wp mls cache clear --confirm
```

This removes all synced data but keeps settings.

## Support

For plugin issues: Check logs at Settings > MLS Settings

For API issues: Contact MLS Grid support at support@mlsgrid.com