# Address autocomplete

`GET /enrichment/address`

API version: `v2026.10.00`. Send `X-Moov-Version: v2026.10.00` to get the behavior described here.

> AI agents: search and read all Moov docs with the docs MCP server at https://docs.moov.io/mcp (no API key). Setup: https://docs.moov.io/guides/developer-tools/mcp-ai/docs-mcp/index.md

Fetch enriched address suggestions. Requires a partial address. 
  
To access this endpoint using an [access token](https://docs.moov.io/api/authentication/access-tokens/)
you'll need to specify the `/profile-enrichment.read` scope.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Moov-Version` | header | string |  | Set this header to v2026.10.00 to use the API described in this specification. When omitted, the server defaults to v2024.01.00, the earliest supported version, which may not match the behavior documented here. An unrecognized well-formed version uses the latest supported version that is not newer than the requested version, when one exists. For example, `v2026.08.00` uses `v2026.07.00`. A malformed value, such as `2022`, returns a `404` response. Values: `v2026.10.00`. |
| `search` | query | string | Yes | Partial or complete address to search. |
| `maxResults` | query | integer |  | Maximum number of results to return. |
| `includeCities` | query | string |  | Limits results to a list of given cities. |
| `includeStates` | query | string |  | Limits results to a list of given states. |
| `includeZipcodes` | query | string |  | Limits results to a list of given zipcodes. |
| `excludeStates` | query | string |  | Exclude list of states from results. No `include` pararmeters may be used with this parameter. |
| `preferCities` | query | string |  | Display results with the listed cities at the top. |
| `preferStates` | query | string |  | Display results with the listed states at the top. |
| `preferZipcodes` | query | string |  | Display results with the listed zipcodes at the top. |
| `preferRatio` | query | integer |  | Specifies the percentage of address suggestions that should be preferred and will appear at the top of the results. |
| `preferGeolocation` | query | string |  | If omitted or set to `city`, it uses the sender's IP address to determine location, then automatically adds the city and state to the preferCities value. This parameter takes precedence over other `include` or `exclude` parameters meaning that if it is not set to `none`, you may see addresses from areas you do not wish to see. |
| `selected` | query | string |  | Useful for narrowing results with `addressLine2` suggestions such as `Apt` (denotes an apartment building with multiple residences). |
| `source` | query | string |  | Include results from alternate data sources. Allowed values are `all` (non-postal addresses), or `postal` (postal addresses only). |

## Response 200

The request completed successfully.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `suggestions` | array of object | Yes |  |
| `suggestions[].addressLine1` | string |  |  |
| `suggestions[].addressLine2` | string |  |  |
| `suggestions[].city` | string |  |  |
| `suggestions[].entries` | integer |  | The number of units at an address. For example the number of apartments or businesses in a building. |
| `suggestions[].postalCode` | string |  |  |
| `suggestions[].stateOrProvince` | string |  |  |

## Errors

| Status | Meaning |
| --- | --- |
| 401 | The request contained missing or expired authentication. |
| 403 | The user is not authorized to make the request. |
| 404 | The requested resource was not found. |
| 429 | Request was refused due to rate limiting. |
| 500 | The request failed due to an unexpected error. |
| 504 | The request failed because a downstream service failed to respond. |

## Examples

### cURL

```bash
curl -X GET "https://api.moov.io/enrichment/address" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.10.00"
```

### Typescript (SDK)

```typescript
import { Moov } from "@moovio/sdk";

const moov = new Moov({
  security: {
    username: "",
    password: "",
  },
});

async function run() {
  const result = await moov.enrichedAddress.get({
    search: "<value>",
  });

  console.log(result);
}

run();
```

Full reference with SDK examples in every language: https://docs.moov.io/api/v2026.10.00/enrichment/form-shortening/address/get/