---
title: "Find Address"
method: GET
path: "/autocomplete/addresses"
tags: ["Address Search"]
---

# Find Address

`GET /autocomplete/addresses`

The Address Autocomplete API delivers address suggestions in order of relevance based on a provided query. It aids real-time address autofill implementations.

Consider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments rather than interacting with this API directly.

## API Usage

Implementing our Address Autocomplete API involves:

1. Fetch address suggestions with `/autocomplete/addresses`
2. Acquire the complete address using the ID from the suggestion

Step 2 will decrement your lookup balance.

Note that step 1 is not a free standalone resource. Integrations that consistently make autocomplete requests without a paid Step 2 request will be rate limited and then suspended.

## Query Filters

Refine results by appending filters to your querystring, e.g., `postcode=sw1a2aa` for postcode `SW1A 2AA`. Invalid filters return an empty set without affecting your lookup count.

To apply multiple filter terms, use a comma-separated list, e.g., `postcode_outward=e1,e2,e3` combines result sets for E1, E2, and E3. Unless otherwise specified, all filters support multiple terms.

Combine filters by `AND` logic, for instance, `su_organisation_indicator=Y&postcode_area=n`. The maximum allowed filter terms is **10**.

## Address Bias

Preface bias searches with `bias_` to boost certain address results. Unlike filters, biasing allows unmatched addresses to appear with lower priority.

For example, use `bias_postcode_area=SW,SE` to favor addresses in the `SW` and `SE` postcode areas. Invalid bias terms have no effect.

Multiple bias terms are allowed unless stated otherwise, with a combined maximum of **5**.

## Suggestion Format

The suggestion format is subject to change. We recommend using the suggestion as-is to prevent potential integration issues.

## Rate Limiting and Cost

The rate limit for the Autocomplete API is 3000 requests per 5 minutes. HTTP Headers inform about the current rate limit.

Autocomplete API usage does not impact your balance, but resolving a suggestion to a full address requires a paid request. Autocomplete requests without subsequent paid requests may result in rate limitation or suspension.

## Query parameters

- `api_key` string
- `query` string
- `dataset` Dataset[]
- `context` string
- `limit` integer
- `bias_lonlat` string
- `bias_ip` 'true'
- `box` string
- `postcode_outward` string
- `postcode` string
- `postcode_area` string
- `postcode_sector` string
- `post_town` string
- `uprn` integer
- `country` string
- `postcode_type` string
- `su_organisation_indicator` string
- `bias_postcode_outward` string
- `bias_postcode` string
- `bias_postcode_area` string
- `bias_postcode_sector` string
- `bias_post_town` string
- `bias_thoroughfare` string
- `bias_country` string

## Response `200`

Success

- AutocompleteResponse
  - `result` object, required
    - `hits` union[], required
      - union
        - AddressSuggestion — Represents an address suggestion for any address in the world
          - `id` string, required — Global unique internally generated identifier for an address
          - `suggestion` string, required — Address Suggestion to be displayed to the user
          - `urls` object, required
        - UkAddressSuggestion — Represents a possible address given an autocomplete query. UK Address Suggestions will return a UDPRN attribute if it references a deliverable endpoint found on Royal Mail's Postcode Address File dataset. UK Address Suggestion will return a UMPRN if it references a multiple occupancy premise found on Royal Mail's Multiple Residence dataset.
          - `id` string, required — Global unique internally generated identifier for an address
          - `suggestion` string, required — Address suggestion for a given query.
          - `udprn` integer, required — UDPRN stands for ‘Unique Delivery Point Reference Number’. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires. Up to 8-digit numeric code. A new UDPRN is automatically assigned to each new Delivery Point added to PAF.
          - `umprn` number — Optionally returned field, representing the UMPRN of a Multiple Residence household
          - `urls` object, required
            - `udprn` string, required — URL to retrieve the entire details for a given address suggestion by the UDPRN
            - `umprn` string — Optionally returned field, to retrieve the entire details for a suggested Multiple Residence household
  - `code` 2000, required
  - `message` 'Success', required

## Other responses

- `400` — Bad Request

---

[API](https://skmtc.net/ideal-postcodes/apis/api-reference.md) · [All operations](https://skmtc.net/ideal-postcodes/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ideal-postcodes/api-reference/revisions/295dd3238f22/schema)