Articles on: Data Normalization

Smart Rules Implementation Guide

Overview


The Smart Rules feature enables you to create unified search experiences across multiple MLSs by defining equivalent values that should be treated as the same. This is essential when working with data from different regions where the same property characteristics are represented using different terminology.


The Problem


Different MLSs often use varying terminology for the same concepts:


  • Property Types: One MLS might use "Single Family Residence" while another uses "Detached" or "House"
  • Property Features: Some MLSs use "Swimming Pool" while others use "Pool" or "In-Ground Pool"
  • Locations: Values like "Miami-Dade" and "Miami-Dade County" refer to the same area


Without Smart Rules, you'd have two problematic options:


  1. Create separate filters for each variation - Leading to a confusing user experience with dozens of redundant filter options
  2. Handle synonym logic in your application - Requiring you to build and maintain complex mapping logic and manually normalize response data


This creates significant development overhead and ongoing maintenance burden as you discover new MLS variations or expand to additional regions.


How It Works


The Smart Rules feature eliminates the need to build complex synonym handling in your application by moving this logic to the API level. Instead of writing code to manage multiple search queries and normalize responses, you simply define your rules once and let the API handle the rest.


Smart Rules work in two ways:


1. Request Matching


When you make an API request with one value, the system automatically searches for all synonymous values defined in your rules.
Example: Searching for propertyType=House will also return listings tagged as "Single Family Residence" and "Detached".


2. Response Normalization (Optional)


You can standardize the values returned in API responses by specifying a normalizedValue. This ensures consistent data presentation regardless of the original MLS terminology.


Benefits Over Application-Level Implementation


Without Smart Rules (Manual Approach)


You would need to:


  • Build search expansion logic - Convert user searches into multiple parameter values before making API calls
  • Build normalization code - Manually standardize response values across different MLS formats
  • Maintain mapping tables - Keep synonym dictionaries updated in your codebase
  • Handle edge cases - Manage conflicts when the same term means different things in different MLSs
  • Scale maintenance - Update your application code every time you discover new MLS variations


Example of the manual approach:


// Without synonymous values, you'd need code like this:
const propertyTypeSynonyms = {
  'House': ['Single Family Residence', 'Detached', 'House', 'SFR'],
  'Condo': ['Condominium', 'Condo', 'Townhouse', 'Unit']
};

function expandSearchTerms(userQuery) {
  const synonyms = propertyTypeSynonyms[userQuery] || [userQuery];
  // Build complex query with all synonym variations
  const queryParams = synonyms.map(term => `propertyType=${encodeURIComponent(term)}`).join('&');
  return `/listings?${queryParams}`;
}

function normalizeResponse(listings) {
  // Complex logic to standardize property types in response
  return listings.map(listing => {
    if (['Single Family Residence', 'Detached', 'SFR'].includes(listing.propertyType)) {
      listing.propertyType = 'House';
    }
    return listing;
  });
}


With Smart Rules (API-Level)


You simply:


  • Define rules once - Configure synonyms at the account level
  • Make single API calls - Search normally, let the API handle expansion
  • Get normalized responses - Receive consistent data automatically
  • Focus on features - Spend time on user experience instead of data wrangling


Basic Implementation


Step 1: Define Your Synonym Rules


Create rules that group equivalent values together: 


{
  "synonyms": [
    {
      "values": ["Single Family Residence", "Detached", "House"],
      "request": { "params": ["propertyType"] },
      "response": {
        "fields": ["details.propertyType"],
        "normalizedValue": "House"
      }
    }
  ]
}



Step 2: Apply Rules to Your Account


Use a PATCH request to configure your synonym rules:

```http
PATCH https://api.repliers.io/accounts/{accountId}
Content-Type: application/json

{
  "rules": {
    "synonyms": [
      {
        "values": ["Single Family Residence", "Detached", "House"],
        "request": { "params": ["propertyType"] },
        "response": { 
          "fields": ["details.propertyType"], 
          "normalizedValue": "House" 
        }
      }
    ]
  }
}


Step 3: Test Your Implementation


Make a search request using one of your normalized values:


GET https://api.repliers.io/listings?propertyType=House


The API will return listings matching "House", "Single Family Residence", and "Detached", with all response values normalized to "House".


Advanced Configurations


Multiple Parameter Support


Apply the same synonym rule to multiple request parameters:


{
  "values": ["Single Family Residence", "Detached", "House"],
  "request": { "params": ["propertyType", "style"] },
  "response": { 
    "fields": ["details.propertyType", "details.style"], 
    "normalizedValue": "House" 
  }
}


This configuration allows the rule to work whether users search by propertyType=House or style=House.


Multiple Synonym Groups


Define multiple synonym groups for different property characteristics:


{
  "synonyms": [
    {
      "values": ["Single Family Residence", "Detached", "House", "SFR"],
      "request": { "params": ["propertyType"] },
      "response": { 
        "fields": ["details.propertyType"], 
        "normalizedValue": "House" 
      }
    },
    {
      "values": ["Swimming Pool", "Pool", "In-Ground Pool"],
      "request": { "params": ["amenities"] },
      "response": { 
        "fields": ["condominium.amenities"], 
        "normalizedValue": "Pool" 
      }
    },
    {
      "values": ["Miami-Dade", "Miami-Dade County"],
      "request": { "params": ["area"] },
      "response": { 
        "fields": ["address.area"], 
        "normalizedValue": "Miami-Dade" 
      }
    }
  ]
}


Search-Only Rules


If you want synonym matching without response normalization, omit the response object:


{
  "values": ["Condo", "Condominium", "Townhouse"],
  "request": { "params": ["propertyType"] }
}


This will expand searches but preserve original MLS terminology in responses.


Managing Your Rules


Viewing Current Rules


Retrieve your current synonym configuration:


GET https://api.repliers.io/accounts/{accountId}


Updating Rules


To modify existing rules, send a complete PATCH request with your updated configuration. The new rules will replace all existing synonym rules.


Rule Priority


When multiple rules could apply to the same value, the system processes them in the order they appear in your configuration array.


Best Practices


1. Start with Common Variations


Begin by identifying the most frequent terminology differences across your target MLSs. Focus on high-impact fields like property types and key amenities.


2. Use Descriptive Normalized Values


Choose normalized values that are clear and commonly understood by your users. Avoid MLS-specific jargon.


3. Test Thoroughly


After implementing rules, test searches using each variation to ensure proper matching and normalization.


4. Monitor and Iterate


Regularly review search analytics to identify new variations that should be added to your synonym rules.


5. Document Your Mappings


Keep a record of your synonym mappings for team reference and future updates.


Common Use Cases


Property Type Standardization 


{
  "values": ["Single Family", "Single Family Residence", "Detached", "House", "SFR"],
  "request": { "params": ["propertyType"] },
  "response": { "fields": ["details.propertyType"], "normalizedValue": "Single Family" }
}


Amenity Normalization


{
  "values": ["Central Air", "Central A/C", "AC", "Air Conditioning", "HVAC"],
  "request": { "params": ["amenities", "features"] },
  "response": { "fields": ["details.amenities"], "normalizedValue": "Air Conditioning" }
}


Status Standardization


{
  "values": ["For Sale", "Active", "Available", "On Market"],
  "request": { "params": ["status"] },
  "response": { "fields": ["details.status"], "normalizedValue": "Active" }
}


Troubleshooting


Rules Not Working


  • Verify that your PATCH request was successful
  • Check that the parameter names in your rules match your API requests
  • Ensure field paths in the response configuration are correct
  • Allow 15-20 minutes for rules to take effect


Unexpected Results


  • Review the order of your synonym rules
  • Check for overlapping rules that might conflict
  • Validate that your normalized values are appropriate


Performance Considerations


  • Synonym matching adds minimal overhead to API requests
  • Large numbers of synonym groups (100+) may slightly impact response times
  • Consider the trade-off between comprehensive coverage and rule complexity


Support


For additional assistance with implementing Smart Rules, contact our support team or refer to the complete API documentation.


Updated on: 21/06/2025

Was this article helpful?

Share your feedback

Cancel

Thank you!