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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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:

{
  "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:

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
  }'

const response = await fetch('https://api.v2.dealmachine.com/v1/properties/search', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dm_sk_live_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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,
  }),
});

const { data, pagination } = await response.json();
console.log(`Found ${pagination.total_results} properties`);

import requests

response = requests.post(
    "https://api.v2.dealmachine.com/v1/properties/search",
    headers={"Authorization": "Bearer dm_sk_live_xxx"},
    json={
        "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,
    },
)

body = response.json()
print(f"Found {body['pagination']['total_results']} properties")

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.

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

Getting Started

Searching

Data & Fields

Responses

Usage

CLI

Reference

AI Assistants

How Locations Work

Location Types

`state`

`county`

`city`

`zip_code`

`radius`

`polygon`

`bounds`

Location Logic

Limits

Complete Example

Common Patterns

Searching

Filters

Credits

Response Format

​How Locations Work

​Location Types

​state

​county

​city

​zip_code

​radius

​polygon

​bounds

​Location Logic

​Limits

​Complete Example

​Common Patterns

​Related Guides

Searching

Filters

Credits

Response Format

How Locations Work

Location Types

`state`

`county`

`city`

`zip_code`

`radius`

`polygon`

`bounds`

Location Logic

Limits

Complete Example

Common Patterns

Related Guides