Synonymous Values Implementation Guide
Overview
The Synonymous Values 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 synonymous values, you'd have two problematic options:
Create separate filters for each variation - Leading to a confusing user experience with dozens of redundant filter options
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 Synonymous Values 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.
Synonymous values 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 Synonymous Values (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 Synonymous Values (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:
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=HouseThe 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 synonymous values, contact our support team or refer to the complete API documentation.
Updated on: 30/05/2025
Thank you!