Locations API Implementation Guide

Overview

The Locations API provides two endpoints for working with geographical data in your real estate application:

• GET /locations - Advanced filtering and querying of location data
• GET /locations/autocomplete - Relevance-based search for typeahead/dropdown interfaces

These endpoints use location terminology that directly matches your MLS data, eliminating the common mismatch issues that occur when using third-party services like Google Maps or Mapbox for location search.

Understanding Location Types

The API recognizes three hierarchical location types:

• area - Larger geographical divisions (synonymous with region, county, parish) that may contain multiple cities and neighborhoods
• city - Municipal divisions (synonymous with town) that can include multiple neighborhoods
• neighborhood - The smallest geographical unit (synonymous with community) within a city

Location Model

Each location entity includes the following structure:

{
    "locationId": "CAONNBWJBFJQLT",
    "name": "Downsview-Roding-CFB",
    "type": "neighborhood",
    "map": {
        "latitude": "43.7298069",
        "longitude": "-79.4923515",
        "point": "POINT (-79.4923515 43.7298069)",
        "boundary": [
            [
                [
                    -79.55113337288341,
                    43.77949638257084
                ],
                [
                    -79.45357859322043,
                    43.802565569203864
                ],
                [
                    -79.42666692986468,
                    43.73381743036484
                ],
                [
                    -79.55113337288341,
                    43.77949638257084
                ]
            ]
        ]
    },
    "address": {
        "state": "ON",
        "country": "CA",
        "city": "Toronto",
        "area": "Toronto",
        "neighborhood": "Downsview-Roding-CFB"
    }
}

GET /locations

Use this endpoint for advanced filtering, pagination, and geographical queries.

Common Use Cases

1. List All Neighborhoods in a City

GET /locations?city=Toronto&type=neighborhood

Returns all neighborhoods within Toronto.

2. List All Cities and Neighborhoods in an Area

GET /locations?area=York%20Region&type=city,neighborhood

Returns all cities and neighborhoods within York Region.

3. Get All Areas in a State

GET /locations?state=MA&typearea

4. Get Locations Within a Radius

GET /locations?lat=43.7298069&long=-79.4923515&radius=5

Returns all locations within 5km of the specified coordinates.

5. Get Locations with Boundaries Only

GET /locations?city=Toronto&hasBoundary=true

Returns only locations that have boundary polygon data, useful for map visualization.

6. Optimize Response Size with Field Selection

GET /locations?city=Toronto&type=neighborhood&fields=name,type,locationId

Returns only the specified fields, reducing payload size for better performance.

GET /locations Parameters Reference

Geographical Filtering with Boundaries

You can filter locations that fall within a custom boundary using GeoJSON polygon format:

GET /locations?map=[[[long1,lat1],[long2,lat2],[long3,lat3],[long1,lat1]]]

Important Notes:

• Coordinates must be in [longitude, latitude] order (WGS 84 format)
• Polygons must be closed (first and last points identical)
• For large polygons, use POST method with map data in request body

Pagination

To paginate through results, use the pageNum and resultsPerPage parameters together. For example, with 50 results per page:

• Page 1: pageNum=1&resultsPerPage=50
• Page 2: pageNum=2&resultsPerPage=50
• Page 3: pageNum=3&resultsPerPage=50

GET /locations/autocomplete

Use this endpoint for implementing search-as-you-type functionality in dropdown menus and search boxes. The endpoint uses relevance-based matching and handles partial searches and spelling mistakes.

Common Use Cases

1. Basic Location Search

GET /locations/autocomplete?search=down

Returns relevant matches like "Downsview-Roding-CFB", "Downtown Toronto", etc.

2. Search Within Specific City

GET /locations/autocomplete?search=park&city=Toronto

Returns only locations containing "park" within Toronto.

3. Search for Specific Location Type

GET /locations/autocomplete?search=york&type=area

Returns only areas (counties/regions) matching "york".

4. Include Boundaries for Map Display

GET /locations/autocomplete?search=downtown&boundary=true

Returns matching locations with their boundary polygons included (adds 10-20ms latency).

GET /locations/autocomplete Parameters Reference

Best Practices

1. Use Field Selection to Optimize Performance

Only request the fields you need to reduce payload size and improve response times:

// Good: Only request needed fields
GET /locations/autocomplete?search=toronto&fields=name,type,locationId

// Avoid: Requesting all data when you only need basic info
GET /locations/autocomplete?search=toronto

2. Implement Proper Debouncing

Debounce autocomplete requests (typically 200-300ms) to reduce unnecessary API calls as users type.

3. Handle Boundary Data Efficiently

Only request boundaries when you need them for map visualization:

// When you need to display on map
GET /locations?city=Toronto&hasBoundary=true&fields=name,map.boundary

// When you only need location names for a list
GET /locations?city=Toronto&fields=name,type

4. Chain Autocomplete with Full Location Queries

Use the autocomplete endpoint to get locationIds based on user search, then use the /locations endpoint with the locationId parameter to retrieve full location details including boundaries and complete address information.

5. Use Hierarchical Filtering

Structure your location selection flow hierarchically for better user experience:

1. First, let users select an area
2. Then show cities within the selected area
3. Finally, show neighborhoods within the selected city

Use the area, city, and type parameters to implement this hierarchy.

Common Integration Patterns

Pattern 1: Property Search by Location

Use the autocomplete endpoint to help users find a location, retrieve the locationId from the selected result, then use that locationId to filter listings in your listings search endpoint.

Pattern 2: Map-Based Exploration

Retrieve locations with boundary polygons using the /locations endpoint with hasBoundary=true, then render these boundaries on your map interface. Users can click on boundary polygons to view properties within that location

Pattern 3: Radius-Based Search

When users click on a map or enter coordinates, use the lat, long, and radius parameters to find all locations within a specific distance. This is useful for "search nearby" functionality.

Pattern 4: Geographical Filtering

Use the map parameter with a custom polygon to find locations within a user-drawn area on a map. This enables "draw a boundary" search functionality.

Troubleshooting

No Results Returned

• Check that location type filters match available data
• Try broader search terms in autocomplete
• Verify geographical coordinates are in the correct format (longitude, latitude order)

Response Times

• Use fields parameter to limit returned data
• Only request boundary data when necessary for map visualization
• Implement proper pagination with reasonable resultsPerPage values
• Use autocomplete endpoint for search operations (it's optimized for speed)

Boundary Polygons Missing

• Not all locations have boundary data available
• Use hasBoundary=true to filter only locations with boundaries
• Use boundary=true in autocomplete when you need boundary data included

Query Parameter Size Limits

If your GeoJSON polygon data exceeds URL query parameter size limits, use the POST method instead of GET and include the map data in the request body.

Support

For additional help or questions about the Locations API, please contact our support team or refer to our complete API documentation.

Updated on: 27/10/2025