Changelog

Cleanse Address now matches addresses outside the UK. Pass context with an ISO 3166-1 alpha-3 country code, such as context=USA or context=FRA, and the API returns the closest matching address from that country's dataset. Requests without context cleanse against the UK, as before.

Details

• One response shape: Every country returns a standardised address in match, the source record in match.native, and the same confidence score and Match Level indicators
• Coverage follows your key: The address datasets your API key is licensed for decide which countries it can cleanse
• Rebuilt matching: A new ranking model improves match accuracy for UK and international addresses, particularly AddressBase Premium and Royal Mail PAF records
• Recalculated confidence scores: Matches, scores and Match Levels may differ from earlier responses. If your integration accepts matches above a fixed confidence threshold, re-check that threshold against current results
• No charge for no match: A cleanse that returns a match costs a lookup. A no-match response is free

See the Cleanse Address API reference.

@ideal-postcodes/sdk is our new TypeScript SDK for the Ideal Postcodes API. It supersedes @ideal-postcodes/core-axios and @ideal-postcodes/core-node with one package that runs in browsers and Node.js 22 or later, has no runtime dependencies and covers every current API operation with generated types.

Details

• Native fetch: Requests use the runtime's own fetch, so there is no Axios or Node-specific client to install or keep up to date
• No runtime dependencies: Installing the SDK adds nothing else to your dependency tree
• Tree-shakeable: Each operation is a named export, so bundlers keep only what you import. A client and findAddress come to about 4.4 kB minified and gzipped
• Every current operation: Postcode lookup, address search, UPRN lookup, address cleanse, email and phone validation, plus key, licensee and configuration management
• Types from the OpenAPI spec: Every request and response is typed, including Royal Mail PAF fields and each dataset's native record
• Autocomplete helper: createAutocomplete debounces keystrokes and exposes find and resolve, ready to wire to your own search box. A search superseded by newer typing resolves undefined rather than throwing, so fast typists produce no unhandled rejections
• Postcode lookup helper: lookupPostcode returns a postcode's addresses and total, the count across all pages. For an unknown postcode it returns the closest matching postcodes instead of throwing
• Client options: timeoutMs rejects any request that runs too long with a TimeoutError, and headers sends default headers, such as User-Agent, with every request
• React and Preact: Optional TanStack Query adapters provide query options for every operation
• Typed errors: HTTP failures throw an ApiError with the status, API error code and message. Pass throwOnError: false to get { data, error } instead
• Management Key kept out of URLs: Account operations send your Management Key in the Authorization header, so it never appears in request URLs, proxy logs or browser history
• Agent skill: npx skills add ideal-postcodes/skills gives coding agents setup guides and a reference for each operation

Start with the TypeScript SDK documentation. Moving from core-axios, core-node or core-browser? The migration guide maps each old call to its SDK equivalent.

Shopify 2 rebuilds our Shopify app on Shopify's native Address Autocomplete API. Suggestions now appear inside Shopify's own address fields at checkout, with no injected search box, and selecting one fills line 1, city, and postcode in a single step. Address blocking, postcode lookup, and the classic search box all ship in the same release.

Bug reports, feature requests, and technical questions now have a home in the open: github.com/ideal-postcodes/feedback. Instead of a private support email, raise it where our engineers work and other developers can see the thread, follow along, and benefit from the answer. Built for people and coding agents alike.

French address searches now run on the Base Adresse Nationale (BAN), France's official national address database. Authoritative, localised address data across mainland France and the overseas territories.

Details

• Official source: The BAN is France's government-maintained national address base, giving standardised coverage nationwide
• Localised formatting: Addresses are parsed and formatted to French conventions, with province and province_code derived from the INSEE code
• New dataset flag: Enable BAN on an API key with the ban dataset flag; France (FRA) is available as a search context

AddressBase Premium is now available across the API. Ordnance Survey's most comprehensive Great Britain address dataset reaches beyond Royal Mail's PAF to include properties with no postal delivery point - subdivided units, multi-occupancy buildings, commercial premises, and objects still under development. Every record carries a UPRN and a rooftop geolocation, alongside the full Ordnance Survey property record. Contact us to enable the abp dataset, then search it through autocomplete, address lookup, and postcode lookup.

Details

• Wider coverage than PAF: AddressBase Premium records every Basic Land and Property Unit in Great Britain, including premises Royal Mail does not hold.
• UPRN and rooftop coordinates on every record: Each result carries Ordnance Survey's Unique Property Reference Number plus a rooftop latitude and longitude. Some records have no Royal Mail UDPRN, since the dataset extends past PAF's delivery points.
• Full Ordnance Survey property record: The native object exposes the consolidated BLPU, DPA, LPI, classification, and street records - land-use classification, multi-occupancy count, street (USRN) and topography (TOID) references, council tax and non-domestic rates references, and lifecycle dates.
• Available everywhere: Select abp on the /autocomplete, /addresses, and /postcodes endpoints. Suggestions show the post town and outward code (for example, ... Brighton, BN41), with full title-cased address lines on resolve.
• Reference: See the AddressBase Premium dataset docs for the full field list.

Add UK address autocomplete to a React app in a single component. The new @ideal-postcodes/react package gives you a drop-in <AddressFinder> with no useEffect or useRef wiring to manage. Install with npm install @ideal-postcodes/react.

Details

• Drop-in component: Render <AddressFinder> and start searching. The widget lifecycle is handled for you, with no manual setup or teardown
• Bring your own input: Let the component render its own field, or wrap an input you already have. It works alongside design systems such as shadcn/ui, MUI, and Mantine
• Every callback as a prop: Each widget event is exposed directly, including onAddressRetrieved. Inline handlers always see your latest state, so there is no need to reach for useCallback
• Styling that fits your build: CSS is injected automatically, or import it yourself for full control under server-side rendering
• Framework ready: Tested with the Next.js App Router ("use client") and Pages Router, Remix, and Astro, on both React 18 and 19

Read the React integration guide to get started. The latest Address Finder (5.2.15) and Postcode Lookup (3.3.2) widget bundles also ship in this release.

Cleanse, verify, and enrich UK addresses without leaving Excel. The new Address Cleanse add-in matches your addresses against the Royal Mail Postcode Address File: drag-select the address column, click Cleanse, and corrected addresses with UPRNs and geocodes are written alongside your data. No exports, no code.

Details

• Cleanse in place: Select one column of freeform addresses, or two columns with a postcode hint, and results are written immediately to the right
• 31 columns per row: Status, formatted address, confidence and fit scores, per-element match levels, geocodes, UPRN, UDPRN, and country data
• Static values: Results persist in the workbook, so it can be shared and reopened by anyone without the add-in or an API key
• All Microsoft 365 platforms: Works in Excel for Windows, Excel for Mac, and Excel for the web
• Key kept private: Your API key is held in Office storage, never in cells or files

Follow the install guide to get started; an AppSource listing is on its way.

Introducing idpc, the Ideal Postcodes command-line interface. Manage your account, clean address data, and validate emails and phone numbers from the terminal. Built for humans and agents.

In agent mode, the CLI will non-interactively emit JSON to stdout and signal failure through exit codes.

Details

• Key management: Check balances, usage, lookup logs, and allowed-URL configurations for your API keys
• Address cleansing: idpc cleanse matches messy addresses against authoritative data, taking a single query, a file, or stdin, with CSV output for batches
• Find and resolve: idpc find returns address suggestions for a partial query; pipe a suggestion ID into idpc resolve for the full record
• Email and phone validation: idpc email and idpc phone mirror the cleanse workflow, with --carrier lookups for phone numbers
• Diagnostics: idpc doctor verifies connectivity and reports whether your key is actually usable, explaining limits or restrictions when it is not

Install with npm install -g @ideal-postcodes/cli. Available on npm.