=== getAddress() Address Autocomplete ===
Contributors: getaddress
Tags: address autocomplete, checkout, australia, denmark, new zealand
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
WC requires at least: 9.9
WC tested up to: 11.1
Stable tag: 0.4.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Australian, Danish and New Zealand address autocomplete at checkout, from official address data. Works on the block and classic checkouts.

== Description ==

Shoppers start typing their address, pick it from a list, and the rest of the address form fills in — street, unit or floor and door, suburb or town, state and postcode. Fewer typos, fewer failed deliveries.

* **Australia** — every address in G-NAF, the Geocoded National Address File, from [getaddress.io](https://getaddress.io).
* **Denmark** — every address in DAR, Danmarks Adresseregister, from [getaddress.dk](https://getaddress.dk).
* **New Zealand** — every address in LINZ's NZ Addresses, from [getaddress.nz](https://getaddress.nz). Postcodes are unofficial (not NZ Post's).

The plugin plugs into WooCommerce's own address autocomplete, so it works on the block checkout and the classic `[woocommerce_checkout]` checkout, on billing and shipping addresses, with WooCommerce's own look.

* **Missing unit numbers caught.** G-NAF knows which buildings have units. Pick an Australian building with units and the plugin opens the apartment line and asks for the unit number — something Google-based autocomplete can't tell you. Danish suggestions already list each flat with its floor and door, and New Zealand ones each unit (2/12 East Street), so there is nothing to ask.
* **Every order checked.** With your API key saved, each new order's delivery address is checked in the background — Australian addresses against G-NAF, Danish ones against DAR, New Zealand ones against LINZ. Addresses that don't exist, buildings missing a unit number (or, in Denmark, a floor and door), and PO Boxes get a private order note, and the Orders list shows a column with the result — so you catch them before you ship.
* **Saved addresses too.** Customers editing their billing or shipping address in My Account get the same suggestions as at checkout, in Australia, Denmark and New Zealand, with the unit prompt and PO Box handling.
* **Business names in the Company field.** Typing in the Company field suggests registered business names — Australian ones from the Australian Business Register with their ABN, state and postcode, Danish ones from CVR with their CVR number, postnummer and town — so the name on the order is spelled the way it is registered. Free: picking a name makes no look-up. Not yet in New Zealand.
* **PO Boxes handled.** Typing a PO Box, GPO Box, Locked Bag or parcel locker (Australia), a Postboks, pakkeboks, parcel shop or Døgnpost (Denmark), or a PO Box, Private Bag, CMB or parcel locker (New Zealand), shows no misleading street suggestions, and you can choose to refuse them as a delivery address (checked on your server, on both checkouts).

Suggestions only appear for a country you have a token for. Other countries' address forms are left exactly as they are.

= What you need =

* WooCommerce 9.9 or later.
* A getAddress() account for each country you sell to ([getaddress.io](https://getaddress.io) for Australia, [getaddress.dk](https://getaddress.dk) for Denmark, [getaddress.nz](https://getaddress.nz) for New Zealand), and a **domain token** for your shop's domain (created in your account under Domain tokens). A domain token only works on the domain it was made for, so it is safe in a web page — never paste an API key there. The countries are separate services: a getaddress.io token or key works only in Australia, a getaddress.dk one only in Denmark, a getaddress.nz one only in New Zealand.

= External services =

This plugin sends what a shopper types into the checkout address field, and the id of the address they pick, from the shopper's browser to getAddress():

* Australian addresses: `https://api.getaddress.io` — [terms](https://getaddress.io/terms), [privacy](https://getaddress.io/PrivacyPolicy).
* Danish addresses: `https://api.getaddress.dk` — [terms](https://getaddress.dk/terms), [privacy](https://getaddress.dk/PrivacyPolicy).
* New Zealand addresses: `https://api.getaddress.nz` — [terms](https://getaddress.nz/terms), [privacy](https://getaddress.nz/PrivacyPolicy).

A request is only made when the shopper has chosen a country you have entered a token for, and has typed at least three characters.

It also sends what a shopper types into the Company field, for business name suggestions, to the same country's service: `https://api.getaddress.io/companies` (Australia) or `https://api.getaddress.dk/companies` (Denmark). New Zealand has none, so nothing is sent for it. Switch them off in the plugin's settings.

**Connect** sends the merchant's browser to `https://getaddress.io/connect` (Australia), `https://getaddress.dk/connect` (Denmark) or `https://getaddress.nz/connect` (New Zealand) with the shop's domain, and the shop's server then exchanges the returned code at that country's `/connect/token` (`https://api.getaddress.io`, `https://api.getaddress.dk` or `https://api.getaddress.nz`) for the domain token and API key; **Disconnect** posts to its `/connect/revoke`. Nothing about shoppers is sent.

If you save an API key for the order address check, your server also sends each new order's delivery address (street lines, town or suburb, state and postcode — no name, email or phone) a moment after the order is placed: Australian addresses to `https://api.getaddress.io/validate`, Danish ones to `https://api.getaddress.dk/datavask/adresser`, New Zealand ones to `https://api.getaddress.nz/validate`. Only for a country you saved a key for; without one, nothing is sent from your server. No name, email, phone number or order details are sent.

== Installation ==

1. Install and activate the plugin.
2. Go to **WooCommerce → Settings → getAddress()** and press **Connect getaddress.io** (Australia), **Connect getaddress.dk** (Denmark), **Connect getaddress.nz** (New Zealand) — each country you sell to. Sign in or sign up there and allow your shop: that country's domain token and API key are filled in and address autocomplete is switched on.
3. Or paste a domain token for each country (and, for the order check, that country's API key) yourself, then switch on **Address autocomplete** under **WooCommerce → Settings → General**. If you have more than one autocomplete provider, choose getAddress() as the preferred one.

== Frequently Asked Questions ==

= Does it cost anything? =

The plugin is free. In every country, address and business name suggestions are free on every getAddress() plan and each address a shopper picks counts as one look-up.

= Does it work with the block checkout? =

Yes, and with the classic shortcode checkout.

= Can I deliver to some states only? =

Yes: WooCommerce → Settings → getAddress() → Delivery rules → "States delivered to". Choose the states and territories you deliver to; an Australian delivery address anywhere else is refused at checkout with a message naming them. Leave it empty to deliver everywhere.

= Can I stop customers using a PO Box for delivery? =

Yes: WooCommerce → Settings → getAddress() → Delivery rules → "Refuse PO Boxes". It covers Australia (PO Box, GPO Box, Locked Bag, parcel lockers), Denmark (Postboks, pakkeboks, parcel shops, Døgnpost) and New Zealand (PO Box, Private Bag, CMB, Counter Delivery, parcel lockers). A rural delivery number (RD 2) is a street address and is never refused. A PO Box stays fine as a billing address.

= What does the order address check cost? =

In Australia, one look-up on your getaddress.io plan for each order whose address is found; an address that isn't found costs nothing. In Denmark, one look-up on your getaddress.dk plan for each order DAR offers any address for — found, missing a floor and door, or a near miss — and nothing when nothing matches at all. In New Zealand, as in Australia: one look-up on your getaddress.nz plan for each order whose address is found. PO Boxes are recognised without a look-up.

= What does the Danish order check look for? =

It sends the address on one line to getaddress.dk's datavask (the address cleaning DAWA had), which reads it the way a person would, forgiving a typo or two. A clear match is Verified. When the house is right but it holds flats and no floor or door was given, the order is noted "Floor/door missing" with the house's address. Anything else — no such address, or several that fit equally — is noted "Not found".

= Where do the business names come from? =

In Australia, the Australian Business Register (ABN Lookup), refreshed weekly by getAddress(); in Denmark, CVR (Det Centrale Virksomhedsregister), active companies only. A business name never fills the address; the shopper still picks their address as usual. Turn the suggestions off under WooCommerce → Settings → getAddress() → Business names.

= Is "Powered by getAddress()" shown to my customers? =

Only if you tick "Credit" in the plugin's settings. It is off by default.

= How fast is it? =

Measured from Sydney against the live service: half of all address suggestions arrive within 28 ms and 95% within 445 ms; business names within 28 ms and 37 ms. The shopper's browser downloads about 6 KB of script (gzip) at checkout, with no Google Maps.

= Is it accessible? =

Yes. The suggestion lists follow the WAI-ARIA combobox pattern: they work with the keyboard alone (arrow keys, Enter, Escape), say how many suggestions there are to screen readers, and pass automated WCAG 2.2 AA checks (axe) on both checkouts and My Account. The unit prompt is announced as a status message and moves the cursor to the unit field. Address suggestions at checkout are drawn by WooCommerce's own accessible autocomplete.

= Which countries? =

Australia, Denmark and New Zealand.

== Screenshots ==

1. Suggestions from G-NAF as the shopper types, on the block checkout.
2. A unit picked: the street on the address line, the unit on the apartment line, and the suburb, state and postcode filled in.
3. A building with units picked without one: the apartment line opens and asks for the unit number.
4. The same on the classic checkout.
5. "Refuse PO Boxes" on: a PO Box is turned away as the delivery address.
6. Orders, with the column from the order address check.
7. Settings: domain token, delivery rules and the order address check.

== Changelog ==

= 0.4.0 =
* New Zealand: every address in LINZ's NZ Addresses through getaddress.nz, on both checkouts and My Account. A pick fills the number and road (2/12 East Street), the suburb on the second line, the town or city and the postcode; the optional region is left blank.
* Order address check: New Zealand delivery addresses checked against LINZ through getaddress.nz's /validate, with its own API key field. A building LINZ holds only as its units, ordered without one, is noted as missing a unit, as in Australia.
* PO Boxes: PO Box, Private Bag, CMB, Counter Delivery, Poste Restante, Freepost and parcel lockers recognised in New Zealand. Rural delivery numbers (RD 2) are not.
* Connect: a third button, Connect getaddress.nz.
* Business names stay Australian and Danish: New Zealand has no business register yet, so its Company fields are left alone.

= 0.3.0 =
* Denmark at parity with Australia. My Account: Danish address suggestions on the saved billing and shipping address forms (floor and door included).
* Denmark costs as Australia: suggestions are free (asked for text only, `kun_tekst=true`); one look-up per address picked, fetched from `/adresser/{id}`. Before, every Danish suggestion list that showed full addresses was a look-up.
* Business names: Danish companies from CVR in the Company field, each with its CVR number, postnummer and town.
* Order address check: Danish delivery addresses checked against DAR through getaddress.dk's datavask, with notes for an address not found, a missing floor and door, or a Postboks. A separate Denmark API key field; each key is checked with its own country before it is saved.
* PO Boxes: Postboks, Pb., Boks, Pakkeboks, Pakkeshop, Pakkeautomat, Døgnpost and Poste restante recognised in Denmark — no address suggestions for them, and refused for delivery when "Refuse PO Boxes" is on.
* Connect: one button per country (getaddress.io, getaddress.dk), each with its own Disconnect.
* The Orders column is named after the register checked (G-NAF or DAR), or "Address check" when orders to both countries are checked.

= 0.2.0 =
* Denmark: addresses from DAR through getaddress.dk, with floor, door and supplerende bynavn.
* Connect: one button signs you in or up at getaddress.io and fills in the domain token and API key; Disconnect revokes them.
* My Account: address suggestions, the unit prompt and PO Box handling on the saved billing and shipping address forms (and business names in their Company field). On by default.
* Delivery rules: "States delivered to" refuses Australian delivery addresses outside the states and territories chosen.
* Accessibility: suggestion lists announce how many suggestions there are to screen readers, and the highlighted one is clearer; checked against WCAG 2.2 AA with axe.

= 0.1.3 =
* Business names: the Company field suggests Australian business names from the Australian Business Register, with ABN, state and postcode. Free, on by default.

= 0.1.2 =
* First release: Australia, block and classic checkout.
* Asks for the unit number when a building with units is picked.
* PO Boxes, Locked Bags and parcel lockers: no street suggestions; optional "Refuse PO Boxes" for delivery.
* Order address check: each new order's delivery address checked against G-NAF, with an order note and a G-NAF column in Orders.
* "Powered by getAddress()" is only shown to shoppers when the merchant opts in.
