Skip to main content
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. 
{
  "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, zip_code), the identifier is always passed in a uniform code field:
TypeDescriptioncode value
stateAn entire US stateTwo-letter abbreviation (e.g., "TX")
countyA US county5-digit FIPS code (e.g., "48201")
zip_codeA ZIP code area5-digit ZIP code (e.g., "78704")
radiusA circle around a pointUses latitude, longitude, radius_miles instead
polygonA custom drawn areaUses coordinates array instead
boundsA rectangular bounding boxUses north, south, east, west instead

​
state

Search an entire US state using its two-letter abbreviation. 
{
  "type": "state",
  "code": "TX"
}
KeyTypeRequiredDescription
typestringYes"state"
codestringYesTwo-letter state abbreviation (e.g., "TX", "CA", "FL")

​
county

Search a specific county using its FIPS code. 
{
  "type": "county",
  "code": "48201"
}
KeyTypeRequiredDescription
typestringYes"county"
codestringYes5-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".

​
zip_code

Search a specific ZIP code area. 
{
  "type": "zip_code",
  "code": "78704"
}
KeyTypeRequiredDescription
typestringYes"zip_code"
codestringYes5-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. 
{
  "type": "radius",
  "latitude": 30.2672,
  "longitude": -97.7431,
  "radius_miles": 5
}
KeyTypeRequiredDescription
typestringYes"radius"
latitudenumberYesCenter point latitude
longitudenumberYesCenter point longitude
radius_milesnumberYesRadius 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. 
{
  "type": "polygon",
  "coordinates": [
    [-97.77, 30.29],
    [-97.71, 30.29],
    [-97.71, 30.24],
    [-97.77, 30.24]
  ]
}
KeyTypeRequiredDescription
typestringYes"polygon"
coordinatesarrayYesArray 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 — just pass the north, south, east, and west boundaries. 
{
  "type": "bounds",
  "north": 30.29,
  "south": 30.24,
  "east": -97.71,
  "west": -97.77
}
KeyTypeRequiredDescription
typestringYes"bounds"
northnumberYesNorth edge latitude (must be greater than south)
southnumberYesSouth edge latitude
eastnumberYesEast edge longitude (must be greater than west)
westnumberYesWest 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: 
{
  "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–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

ConstraintLimit
Locations per request15 max
Minimum locations1 required
Polygon coordinates3 minimum

​
Complete Example

Find high-equity absentee-owned properties across multiple locations in Texas: 
curl -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

Add each ZIP code as a separate location object. They combine with OR logic, so results in any of the ZIP codes are returned.
{
  "locations": [
    { "type": "zip_code", "code": "78701" },
    { "type": "zip_code", "code": "78702" },
    { "type": "zip_code", "code": "78703" },
    { "type": "zip_code", "code": "78704" }
  ]
}
You can combine any location types in a single request. For example, search an entire state plus specific ZIP codes in another state:
{
  "locations": [
    { "type": "state", "code": "FL" },
    { "type": "zip_code", "code": "78704" },
    { "type": "zip_code", "code": "78705" }
  ]
}
Use a radius location to search around a specific point. This is useful when you have an address or intersection you want to target:
{
  "locations": [
    {
      "type": "radius",
      "latitude": 33.749,
      "longitude": -84.388,
      "radius_miles": 2
    }
  ]
}
Pass the edges of a rectangular area. This is the easiest way to search what’s visible on a map:
{
  "locations": [
    {
      "type": "bounds",
      "north": 33.77,
      "south": 33.73,
      "east": -84.37,
      "west": -84.42
    }
  ]
}
Draw a precise boundary using polygon coordinates. Useful for irregular areas like neighborhoods, school districts, or custom territories:
{
  "locations": [
    {
      "type": "polygon",
      "coordinates": [
        [-84.42, 33.77],
        [-84.37, 33.77],
        [-84.37, 33.73],
        [-84.40, 33.71],
        [-84.42, 33.73]
      ]
    }
  ]
}

Searching

The full search workflow including locations, filters, fields, and pagination.

Filters

Narrow results within your locations using filter criteria.

Credits

Understand how search requests consume credits.

Response Format

Understand the data + pagination response envelope.