> ## 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.
# List Locations
Search for US locations by name. Use this endpoint to find FIPS codes for counties, place IDs for cities, look up ZIP codes, or browse states so you can pass the right `code` values to your [property](/api-reference/properties/search-properties) and [people](/api-reference/people/search-people) searches.
Not sure what FIPS code to use for a county? Search by name here, then pass the returned `code`
directly into your search request's [locations](/concepts/locations) array.
For interactive address or city entry, use [Autocomplete Addresses](/api-reference/addresses/autocomplete-addresses). It is bounded to 10 suggestions, skips the count query, and can return both address components and normalized DealMachine locations.
## Query Parameters
Search query. Matches against location names, location codes, state abbreviations, and common place-name abbreviations. Minimum 1 character.
Examples: `"Harris"`, `"Travis County"`, `"St. Louis"`, `"saint louis"`, `"9021"`, `"MO"`, `"Missouri"`
Filter results to a specific location type.
Options: `county`, `city`, `zip_code`, `state`
When omitted, all matching location types are returned.
Filter results to a specific state. Two-letter state abbreviation (e.g., `"TX"`, `"CA"`).
Useful when searching for common county names that exist in multiple states (e.g., "Washington County" exists in 30 states).
Number of results to return per page. Maximum `100`.
Page number for paginated results.
***
```bash cURL: Search counties by name theme={null}
curl "https://api.v2.dealmachine.com/v1/locations?q=Harris&type=county" \
-H "Authorization: Bearer dm_sk_live_xxx"
```
```bash cURL: Search counties with state filter theme={null}
curl "https://api.v2.dealmachine.com/v1/locations?q=Washington&type=county&state=OR" \
-H "Authorization: Bearer dm_sk_live_xxx"
```
```bash cURL: Search cities by name theme={null}
curl "https://api.v2.dealmachine.com/v1/locations?q=saint%20louis&type=city&state=MO" \
-H "Authorization: Bearer dm_sk_live_xxx"
```
```bash cURL: Search states by abbreviation theme={null}
curl "https://api.v2.dealmachine.com/v1/locations?q=MO&type=state" \
-H "Authorization: Bearer dm_sk_live_xxx"
```
```typescript Node.js theme={null}
const params = new URLSearchParams({
q: 'Harris',
type: 'county',
});
const response = await fetch(`https://api.v2.dealmachine.com/v1/locations?${params}`, {
headers: {
Authorization: `Bearer ${apiKey}`,
},
});
const { data, pagination } = await response.json();
for (const location of data) {
console.log(`${location.name} - FIPS: ${location.code} (${location.state})`);
}
// Harris County - FIPS: 48201 (TX)
// Harrison County - FIPS: 28047 (MS)
// ...
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.v2.dealmachine.com/v1/locations",
headers={"Authorization": f"Bearer {api_key}"},
params={
"q": "Harris",
"type": "county",
},
)
body = response.json()
for location in body["data"]:
print(f"{location['name']} - FIPS: {location['code']} ({location['state']})")
```
```json 200 County Search theme={null}
{
"data": [
{
"location_id": "loc_county_48201",
"type": "county",
"code": "48201",
"name": "Harris County",
"state": "TX",
"state_name": "Texas",
"property_count": 1842305
},
{
"location_id": "loc_county_28047",
"type": "county",
"code": "28047",
"name": "Harrison County",
"state": "MS",
"state_name": "Mississippi",
"property_count": 87421
},
{
"location_id": "loc_county_39067",
"type": "county",
"code": "39067",
"name": "Harrison County",
"state": "OH",
"state_name": "Ohio",
"property_count": 12034
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total_results": 3,
"total_pages": 1
}
}
```
```json 200 ZIP Code Search theme={null}
{
"data": [
{
"location_id": "loc_zip_code_90210",
"type": "zip_code",
"code": "90210",
"name": "Beverly Hills",
"state": "CA",
"state_name": "California",
"property_count": 15832
},
{
"location_id": "loc_zip_code_90211",
"type": "zip_code",
"code": "90211",
"name": "Beverly Hills",
"state": "CA",
"state_name": "California",
"property_count": 4210
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total_results": 2,
"total_pages": 1
}
}
```
```json 200 City Search theme={null}
{
"data": [
{
"location_id": "loc_city_48106",
"type": "city",
"code": "48106",
"name": "St. Louis",
"state": "MO",
"state_name": "Missouri",
"property_count": 215360
},
{
"location_id": "loc_city_45920",
"type": "city",
"code": "45920",
"name": "St. Louis",
"state": "IL",
"state_name": "Illinois",
"property_count": 290
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total_results": 2,
"total_pages": 1
}
}
```
```json 200 All Types theme={null}
{
"data": [
{
"location_id": "loc_state_FL",
"type": "state",
"code": "FL",
"name": "Florida",
"property_count": 10245831
},
{
"location_id": "loc_county_12086",
"type": "county",
"code": "12086",
"name": "Floyd County",
"state": "GA",
"state_name": "Georgia",
"property_count": 48210
},
{
"location_id": "loc_city_24234",
"type": "city",
"code": "24234",
"name": "Florence",
"state": "AL",
"state_name": "Alabama",
"property_count": 18240
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total_results": 2,
"total_pages": 1
}
}
```
```json 400 Validation Error theme={null}
{
"error": {
"code": "validation_error",
"message": "Validation failed",
"request_id": "req_abc123def456",
"details": {
"issues": [
{
"path": "q",
"message": "Search query must be at least 1 character"
}
]
}
}
}
```
```json 401 Unauthorized theme={null}
{
"error": {
"code": "invalid_api_key",
"message": "The provided API key is invalid",
"request_id": "req_def456ghi789"
}
}
```
## Response Fields
### Location Object
The shape of each location object depends on its `type`:
#### All Types
| Field | Type | Description |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `location_id` | string | Unique DealMachine location identifier (e.g., `"loc_county_48201"`, `"loc_city_7333"`, `"loc_zip_code_90210"`, `"loc_state_FL"`) |
| `type` | string | Location type: `"state"`, `"county"`, `"city"`, or `"zip_code"` |
| `code` | string | The code to use in search location objects (state abbreviation, FIPS code, city place ID, or ZIP code) |
| `name` | string | Human-readable name (e.g., `"Harris County"`, `"Florida"`, `"Beverly Hills"`) |
| `property_count` | integer | Approximate number of properties in this location |
#### County-specific
| Field | Type | Description |
| ------------ | ------ | ----------------------------- |
| `state` | string | Two-letter state abbreviation |
| `state_name` | string | Full state name |
#### ZIP Code-specific
| Field | Type | Description |
| ------------ | ------ | ----------------------------- |
| `state` | string | Two-letter state abbreviation |
| `state_name` | string | Full state name |
#### City-specific
| Field | Type | Description |
| ------------ | ------ | ----------------------------- |
| `state` | string | Two-letter state abbreviation |
| `state_name` | string | Full state name |
### Pagination
| Field | Type | Description |
| --------------- | ------- | ------------------------ |
| `page` | integer | Current page number |
| `per_page` | integer | Results per page |
| `total_results` | integer | Total matching locations |
| `total_pages` | integer | Total number of pages |
## Using Results in Searches
The `code` returned for each location is the exact value you pass into a search request's `locations` array:
```json theme={null}
// 1. Search for "Harris" to find the FIPS code
// GET /v1/locations?q=Harris&type=county
// → Returns { "location_id": "loc_county_48201", "code": "48201", "name": "Harris County", ... }
// 2. Use the code in a property search
{
"locations": [
{ "type": "county", "code": "48201" }
],
"filters": [...]
}
```
## Credits
This endpoint does **not** consume credits. Location lookups are included with your API plan.
## Notes
* Search is case-insensitive and matches partial names, codes, state abbreviations, and state names. Searching `"MO"` with `type=state` returns Missouri. Searching `"har"` will match "Harris County", "Harrison County", "Hardeman County", etc.
* Common place-name abbreviations are normalized across location types. Searching `"saint louis"` and `"st louis"` returns the same matching city and county names.
* Results are ranked by relevance: exact matches appear first, followed by prefix matches, then partial matches.
* The `property_count` is an approximate count and is updated periodically. Use [Count Properties](/api-reference/properties/count-properties) for precise counts with filters applied.
* When the `state` query parameter is used with `type=state`, it filters to that specific state.
* ZIP codes that span multiple counties return the primary county.