homeproz/wp-content/plugins/mls-by-hansonxyz/docs/USAGE.md

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:

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

Smart Sync (Recommended)

The wp mls run command is the recommended way to sync. It automatically handles all scenarios:

wp mls run                    # Smart sync with progress
wp mls run --quiet            # Status messages only
wp mls run --verbose          # Full API details
wp mls run --silent           # For cron (no output)

What it does automatically:

• If a sync is already running: aborts (prevents duplicates)
• If a previous sync failed/interrupted: resumes it
• If no data exists: runs full sync
• Otherwise: runs incremental sync

Failed syncs are automatically resumed on the next run - no manual intervention needed.

Manual Sync Commands

For more control, use the individual sync commands:

# 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

# Use --verbose for detailed output
wp mls sync full --verbose
wp mls sync incremental --verbose

Progress Indicators

During sync, you'll see progress characters:

• . = new property
• # = updated property
• x = deleted property
• P = photo downloaded
• p = photo skipped (exists)
• E = photo error
• | = page complete

Use --verbose for detailed timestamped output showing API requests and individual items.

Via Unix Cron

Add to your system crontab (crontab -e) for scheduled sync:

# Smart sync every 15 minutes (recommended)
# Automatically handles: initial sync, incremental updates, and error recovery
*/15 * * * * cd /var/www/html && wp mls run --silent --allow-root >> /var/log/mls-sync.log 2>&1

That's it! The wp mls run command handles everything automatically:

• First run: performs full initial sync
• Subsequent runs: performs incremental sync
• After failures: resumes from where it left off
• Concurrent runs: safely aborts if another sync is running

For more control, use the individual commands:

# Incremental sync every hour
0 * * * * cd /var/www/html && wp mls sync incremental --allow-root >> /var/log/mls-sync.log 2>&1

# Full sync weekly (Sunday at 3am) to rebuild from scratch
0 3 * * 0 cd /var/www/html && wp mls sync full --allow-root >> /var/log/mls-sync.log 2>&1

Important Notes:

• Use --allow-root when running as root user
• Redirect output to a log file for debugging
• MLS Grid requires refresh at least every 12 hours per IDX rules
• The plugin handles rate limits automatically (waits if approaching limits)
• Media images are fetched on-demand when properties are viewed (no separate cron needed)

Via WP-Cron (Alternative)

Enable auto-sync in Settings > MLS Settings to use WordPress's built-in cron system. This runs on page loads rather than true system cron, so may be less reliable for high-frequency syncs.

Checking Status

Via Admin

Settings > MLS Settings shows:

• Database statistics (property counts by status)
• Last sync time and results
• Rate limit usage

Via CLI

# 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:

// 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:

$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:

$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:

wp mls cache clear --confirm

This removes all synced data but keeps settings.

Missing Media Log

Failed media downloads are logged for review:

# View missing media log
wp mls cache missing

# View first 20 entries
wp mls cache missing --limit=20

# Clear the log
wp mls cache missing --clear

Log location: wp-content/uploads/mls-missing-media.log

The log shows listing key, media key, error type, and original URL for each failed download. Media downloads automatically retry with exponential backoff (up to 5 attempts) for rate limit and server errors.

Support

For plugin issues: Check logs at Settings > MLS Settings

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