Locations
Locations define where you want to search. Every property and people search requires at least one location. You can include up to 15 locations per request, and they are combined with OR logic. Results matching any of the locations are returned.
Locations are separate from filters. Filters narrow what you're looking for
(equity, property type, owner details). Locations define where you're looking.
How Locations Work
Locations are passed alongside filters in your search request. While filters use AND logic (every filter must match), locations use OR logic. A record only needs to match one of your locations to be included.
1234567{ "locations": [ { "type": "state", "code": "TX" }, { "type": "zip_code", "code": "90210" } ], "filters": [...] }
This searches for results in Texas OR ZIP code 90210, then applies all filters on top.
Location Types
Each location object requires a
type field that determines its shape. For standard location types (state, county, city, zip_code), the identifier is always passed in a uniform code field:| Type | Description | code value |
state | An entire US state | Two-letter abbreviation (e.g., "TX") |
county | A US county | 5-digit FIPS code (e.g., "48201") |
city | A city or place | Place ID from List Locations (e.g., "7333" for Austin, TX) |
zip_code | A ZIP code area | 5-digit ZIP code (e.g., "78704") |
radius | A circle around a point | Uses latitude, longitude, radius_miles instead |
polygon | A custom drawn area | Uses coordinates array instead |
bounds | A rectangular bounding box | Uses north, south, east, west instead |
state
Search an entire US state using its two-letter abbreviation.
1234{ "type": "state", "code": "TX" }
| Key | Type | Required | Description |
type | string | Yes | "state" |
code | string | Yes | Two-letter state abbreviation (e.g., "TX", "CA", "FL") |
county
Search a specific county using its FIPS code.
1234{ "type": "county", "code": "48201" }
| Key | Type | Required | Description |
type | string | Yes | "county" |
code | string | Yes | 5-digit FIPS county code (e.g., "48201" for Harris County, TX) |
Not sure what FIPS code to use? Use the List Locations
endpoint to look up counties by name and get their FIPS codes. For example, searching
"Harris"
returns Harris County, TX with code "48201".city
Search a specific city using its DealMachine place ID.
1234{ "type": "city", "code": "7333" }
| Key | Type | Required | Description |
type | string | Yes | "city" |
code | string | Yes | Place ID from the List Locations endpoint |
Search the List Locations endpoint with
type=city to
find the right place ID. For example, searching "Austin" with state=TX returns Austin, TX with
code "7333". Common abbreviations are normalized, so "St. Louis" and "Saint Louis" return
the same matching city names.zip_code
Search a specific ZIP code area.
1234{ "type": "zip_code", "code": "78704" }
| Key | Type | Required | Description |
type | string | Yes | "zip_code" |
code | string | Yes | 5-digit ZIP code (e.g., "78704") |
radius
Search a circular area around a geographic point. Useful for targeting a neighborhood or proximity to a specific address.
123456{ "type": "radius", "latitude": 30.2672, "longitude": -97.7431, "radius_miles": 5 }
| Key | Type | Required | Description |
type | string | Yes | "radius" |
latitude | number | Yes | Center point latitude |
longitude | number | Yes | Center point longitude |
radius_miles | number | Yes | Radius in miles (e.g., 5 for a 5-mile radius) |
polygon
Search a custom-drawn area defined by a series of coordinate pairs. The polygon is automatically closed. You do not need to repeat the first coordinate at the end.
123456789{ "type": "polygon", "coordinates": [ [-97.77, 30.29], [-97.71, 30.29], [-97.71, 30.24], [-97.77, 30.24] ] }
| Key | Type | Required | Description |
type | string | Yes | "polygon" |
coordinates | array | Yes | Array of [longitude, latitude] pairs defining the polygon boundary. Minimum 3 points. |
Coordinate pairs use longitude-first order:
[longitude, latitude]. This follows the GeoJSON
standard and is the opposite of how coordinates
are typically spoken ("lat/long").bounds
Search a rectangular area defined by its four edges. This is the simplest way to search a map viewport or any rectangular region. Pass the north, south, east, and west boundaries.
1234567{ "type": "bounds", "north": 30.29, "south": 30.24, "east": -97.71, "west": -97.77 }
| Key | Type | Required | Description |
type | string | Yes | "bounds" |
north | number | Yes | North edge latitude (must be greater than south) |
south | number | Yes | South edge latitude |
east | number | Yes | East edge longitude (must be greater than west) |
west | number | Yes | West edge longitude |
The
bounds type is equivalent to a polygon with four corners. Use it when you have a
rectangular area (like a map viewport) and don't want to construct coordinate pairs manually.Location Logic
Locations use OR logic. A record is included if it falls within any of the provided locations:
1234567891011121314{ "locations": [ { "type": "county", "code": "48201" }, { "type": "county", "code": "48113" }, { "type": "zip_code", "code": "78704" } ], "filters": [ { "filter_id": "estimated_value", "operator": "range", "value": { "min": 200000, "max": 500000 } } ] }
This returns properties valued between $200k–$500k that are in Harris County, TX OR Dallas County, TX OR ZIP code 78704.
Think of it this way:
- Locations define your search area (OR, expand the area)
- Filters narrow your results within that area (AND, tighten the criteria)
Limits
| Constraint | Limit |
| Locations per request | 15 max |
| Minimum locations | 1 required |
| Polygon coordinates | 3 minimum |
Complete Example
Find high-equity absentee-owned properties across multiple locations in Texas:
123456789101112131415161718192021222324curl -X POST "https://api.v2.dealmachine.com/v1/properties/search" \ -H "Authorization: Bearer dm_sk_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "locations": [ { "type": "county", "code": "48201" }, { "type": "county", "code": "48113" }, { "type": "radius", "latitude": 30.2672, "longitude": -97.7431, "radius_miles": 10 } ], "filters": [ { "filter_id": "equity_percent", "operator": "greater_than_or_equal", "value": 40 }, { "filter_id": "is_absentee_owner", "value": true } ], "fields": ["estimated_value", "equity_percent", "owner_name"], "page": 1, "per_page": 25 }'
Common Patterns
Search multiple ZIP codes
Add each ZIP code as a separate location object. They combine with OR logic, so results in any of the ZIP codes are returned.
12345678{ "locations": [ { "type": "zip_code", "code": "78701" }, { "type": "zip_code", "code": "78702" }, { "type": "zip_code", "code": "78703" }, { "type": "zip_code", "code": "78704" } ] }
Mix location types
You can combine any location types in a single request. For example, search an entire state plus specific ZIP codes in another state:
1234567{ "locations": [ { "type": "state", "code": "FL" }, { "type": "zip_code", "code": "78704" }, { "type": "zip_code", "code": "78705" } ] }
Target a neighborhood with radius
Use a radius location to search around a specific point. This is useful when you have an address or intersection you want to target:
12345678910{ "locations": [ { "type": "radius", "latitude": 33.749, "longitude": -84.388, "radius_miles": 2 } ] }
Search a map viewport with bounds
Pass the edges of a rectangular area. This is the easiest way to search what's visible on a map:
1234567891011{ "locations": [ { "type": "bounds", "north": 33.77, "south": 33.73, "east": -84.37, "west": -84.42 } ] }
Define a custom boundary with polygon
Draw a precise boundary using polygon coordinates. Useful for irregular areas like neighborhoods, school districts, or custom territories:
1234567891011121314{ "locations": [ { "type": "polygon", "coordinates": [ [-84.42, 33.77], [-84.37, 33.77], [-84.37, 33.73], [-84.40, 33.71], [-84.42, 33.73] ] } ] }