> ## Documentation Index
> Fetch the complete documentation index at: https://api.docs.dealmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Locations

> Define the geographic areas for your property and people searches

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.

<Info>
  Locations are separate from [filters](/concepts/filters). Filters narrow *what* you're looking for
  (equity, property type, owner details). Locations define *where* you're looking.
</Info>

## 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.

```json theme={null}
{
  "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](/api-reference/locations/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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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) |

<Tip>
  Not sure what FIPS code to use? Use the [List Locations](/api-reference/locations/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"`.
</Tip>

### `city`

Search a specific city using its DealMachine place ID.

```json theme={null}
{
  "type": "city",
  "code": "7333"
}
```

| Key    | Type   | Required | Description                                                                          |
| ------ | ------ | -------- | ------------------------------------------------------------------------------------ |
| `type` | string | Yes      | `"city"`                                                                             |
| `code` | string | Yes      | Place ID from the [List Locations](/api-reference/locations/list-locations) endpoint |

<Tip>
  Search the [List Locations](/api-reference/locations/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.
</Tip>

### `zip_code`

Search a specific ZIP code area.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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. |

<Warning>
  Coordinate pairs use **longitude-first** order: `[longitude, latitude]`. This follows the [GeoJSON
  standard](https://datatracker.ietf.org/doc/html/rfc7946) and is the opposite of how coordinates
  are typically spoken ("lat/long").
</Warning>

### `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.

```json theme={null}
{
  "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                                |

<Tip>
  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.
</Tip>

***

## Location Logic

Locations use **OR** logic. A record is included if it falls within **any** of the provided locations:

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript Node.js theme={null}
  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`);
  ```

  ```python Python theme={null}
  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")
  ```
</CodeGroup>

## Common Patterns

<AccordionGroup>
  <Accordion title="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.

    ```json theme={null}
    {
      "locations": [
        { "type": "zip_code", "code": "78701" },
        { "type": "zip_code", "code": "78702" },
        { "type": "zip_code", "code": "78703" },
        { "type": "zip_code", "code": "78704" }
      ]
    }
    ```
  </Accordion>

  <Accordion title="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:

    ```json theme={null}
    {
      "locations": [
        { "type": "state", "code": "FL" },
        { "type": "zip_code", "code": "78704" },
        { "type": "zip_code", "code": "78705" }
      ]
    }
    ```
  </Accordion>

  <Accordion title="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:

    ```json theme={null}
    {
      "locations": [
        {
          "type": "radius",
          "latitude": 33.749,
          "longitude": -84.388,
          "radius_miles": 2
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="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:

    ```json theme={null}
    {
      "locations": [
        {
          "type": "bounds",
          "north": 33.77,
          "south": 33.73,
          "east": -84.37,
          "west": -84.42
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Define a custom boundary with polygon">
    Draw a precise boundary using polygon coordinates. Useful for irregular areas like neighborhoods, school districts, or custom territories:

    ```json theme={null}
    {
      "locations": [
        {
          "type": "polygon",
          "coordinates": [
            [-84.42, 33.77],
            [-84.37, 33.77],
            [-84.37, 33.73],
            [-84.40, 33.71],
            [-84.42, 33.73]
          ]
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Related Guides

<CardGroup cols={2}>
  <Card title="Searching" icon="magnifying-glass" href="/concepts/searching">
    The full search workflow including locations, filters, fields, and pagination.
  </Card>

  <Card title="Filters" icon="filter" href="/concepts/filters">
    Narrow results within your locations using filter criteria.
  </Card>

  <Card title="Credits" icon="coins" href="/concepts/credits">
    Understand how search requests consume credits.
  </Card>

  <Card title="Response Format" icon="brackets-curly" href="/concepts/response-format">
    Understand the data + pagination response envelope.
  </Card>
</CardGroup>