Filter and bias

Filters restrict address suggestions to matching addresses. Biases rank matching addresses first but still return the rest. Both are query parameters on findAddress, and the autocomplete helper accepts them alongside query in find.

Filter to an area

Add a filter, such as postcode_outward, to the query.

filter.tsts

import { createIdpcClient, findAddress } from "@ideal-postcodes/sdk";

const client = createIdpcClient({ apiKey: "ak_test" });
const { data } = await findAddress({
  client,
  query: { query: "malyons road", postcode_outward: "BR8" },
});
console.log(data.result.hits);

With the autocomplete helper, pass the same parameter to find:

filter-autocomplete.tsts

const hits = await autocomplete.find({ query: "high street", country: "Wales" });

An invalid filter term returns an empty list.

Bias towards an area

Add a bias, such as bias_post_town. Addresses outside the post town still appear, ranked lower.

bias.tsts

const { data } = await findAddress({
  client,
  query: { query: "high street", bias_post_town: "Edinburgh" },
});

To favour addresses near a point, pass bias_lonlat as longitude, latitude and radius in metres. To favour addresses near the user, set bias_ip to "true". The API uses the approximate location of the IP address that sends the request, so call it from the browser rather than your server.

bias-location.tsts

const near = await autocomplete.find({
  query: "high street",
  bias_lonlat: "-0.12767,51.503541,5000",
});

An invalid bias term has no effect.

Filters

Filter	Restricts suggestions to	Example
postcode	A full postcode	BR8 7RE
postcode_outward	An outward code, the first half of a postcode	BR8
postcode_area	A postcode area, the leading letters of a postcode	BR
postcode_sector	A postcode sector, the outward code plus the first digit of the inward code	BR8 7
post_town	A Royal Mail post town, city or locality	London
uprn	One UPRN. Takes a number and accepts a single term only	50002012147
country	A country: England, Scotland, Wales, Northern Ireland, Jersey, Guernsey or Isle of Man	Scotland
postcode_type	Royal Mail postcode user type: S small user, L large user	L

country never takes United Kingdom. Pass one of the seven values above.

A small user postcode covers a group of delivery points, 19 on average and never more than 100. A large user postcode belongs to one address, because of the volume of mail it receives or because it has a PO Box or Selectapost service.

Biases

Bias	Ranks first	Example
bias_postcode	A full postcode	BR8 7RE
bias_postcode_outward	An outward code	BR8
bias_post_town	A post town, city or locality	Manchester
bias_lonlat	A circle given as longitude,latitude,radius, radius in metres up to 50000	-2.095,57.15,100
bias_ip	The approximate location of the requesting IP address. Takes "true" only	"true"

Multiple terms

Separate terms with commas to match any of them, such as postcode_area: "SW,SE". Separate filters combine, so each one narrows the list further.

The API accepts at most 8 filter terms and 5 bias terms per request. uprn takes one term, and bias_lonlat takes one circle.

See findAddress for every parameter and the API reference for the underlying request.