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

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

# 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

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

Support

For plugin issues: Check logs at Settings > MLS Settings

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