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

# Autocomplete Addresses

Return fast, bounded suggestions for US street addresses and normalized DealMachine locations. Use
this endpoint in address inputs, city and county pickers, and workflows where a user has not
supplied an exact DealMachine location.

Autocomplete is free and does not perform property or person enrichment. It does not accept
`fields`, `contact_audience`, or other enrichment controls. Address results contain address
components and may include a normalized DealMachine city or county location for a later explicit
search or enrichment request.

<Tip>
  A ZIP code is returned with an address when the provider supplies one, but ZIP is not used to
  select the normalized city or county. City matching uses city and state, then falls back to county
  and state.
</Tip>

<Note>
  `GET /v1/locations/autocomplete` remains available as a deprecated compatibility alias. New
  integrations should use this addresses Endpoint.
</Note>

## Query Parameters

<ParamField query="q" type="string" required>
  At least two characters of a street address, city, county, state, or ZIP code. Maximum 200 characters.
</ParamField>

<ParamField query="scope" type="string" default="all">
  Choose `all`, `address`, or `location`. Use `address` for a street-address input and `location` for a city, county, state, or ZIP picker.
</ParamField>

<ParamField query="state" type="string">
  Optional two-letter state abbreviation used to prefer and normalize results in one state.
</ParamField>

<ParamField query="limit" type="integer" default="5">
  Maximum suggestions to return. Minimum 1 and maximum 10.
</ParamField>

<ParamField query="latitude" type="number">
  Optional latitude for nearby address ranking. `longitude` is required when this parameter is supplied.
</ParamField>

<ParamField query="longitude" type="number">
  Optional longitude for nearby address ranking. `latitude` is required when this parameter is supplied.
</ParamField>

<RequestExample>
  ```bash cURL: Address and location suggestions theme={null}
  curl "https://api.v2.dealmachine.com/v1/addresses/autocomplete?q=1200%20Barton%20Springs&state=TX&limit=5" \
    -H "Authorization: Bearer dm_sk_live_xxx"
  ```

  ```bash cURL: Normalized city and county suggestions only theme={null}
  curl "https://api.v2.dealmachine.com/v1/addresses/autocomplete?q=saint%20louis%2063101&scope=location" \
    -H "Authorization: Bearer dm_sk_live_xxx"
  ```

  ```typescript Node.js theme={null}
  const params = new URLSearchParams({
    q: inputValue,
    scope: 'all',
    limit: '5',
  });

  const response = await fetch(
    `https://api.v2.dealmachine.com/v1/addresses/autocomplete?${params}`,
    { headers: { Authorization: `Bearer ${apiKey}` } },
  );

  const { data, meta } = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Address suggestion theme={null}
  {
    "data": [
      {
        "suggestion_id": "addr_address_123",
        "kind": "address",
        "label": "1200 Barton Springs Rd, Austin, Texas 78704, United States",
        "address": {
          "address": "1200 Barton Springs Rd",
          "city": "Austin",
          "county": "Travis County",
          "state": "TX",
          "zip": "78704",
          "full_address": "1200 Barton Springs Rd, Austin, Texas 78704, United States",
          "latitude": 30.2638,
          "longitude": -97.7714
        },
        "location": {
          "location_id": "loc_city_7333",
          "type": "city",
          "code": "7333",
          "name": "Austin",
          "property_count": 460000,
          "state": "TX",
          "state_name": "Texas"
        }
      }
    ],
    "meta": {
      "query": "1200 Barton Springs",
      "scope": "all",
      "limit": 5,
      "returned": 1,
      "partial_results": false
    }
  }
  ```
</ResponseExample>

## App integration best practices

Wait until the user has entered at least two characters, debounce requests for about 200
milliseconds, and cancel any previous request when the input changes. Keep `limit=5` for most menus
and use `scope=address` when the control accepts only a street address.

Treat each suggestion as discovery data. Do not expect fields or enrichment output from this
endpoint. After selection, pass the returned address to an enrichment Endpoint or pass
`location.location_id` or `location.code` to a search Endpoint.

`partial_results=true` means the address provider was unavailable or exceeded its short timeout.
The Endpoint still returns any normalized DealMachine location suggestions that were available, so
the UI can remain usable without waiting on the address provider.