All tutorials

Installing the Magento 2 extension

intermediate

The what3words Magento 2 extension allows you to add a 3 word address field to a checkout page. Store users can then add a 3 word address to orders and are provided 3 word address suggestions as they type. The user can also save 3 word addresses to their account for future use.

Magento 2 Minimum Supported Version: 2.3, 2.4, 2.4.4, 2.4.5

1
2

Installation

The Magento 2 Extension can be installed using Composer and Packagist to ensure that all dependencies are installed along with the Extension.

To add the what3words Magento 2 Extension to a store using composer and packagist, first connect to your server and start the command line interface.

From the CLI run the composer command to install the files and dependencies required by the extension:

composer require what3words/module-what3words
Copied

Next, to compile the site to ensure it includes the new extension run the following commands (as with any other Magento module):

php bin/magento deploy:mode:set --skip-compilation production
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy # here set the themes to be compiled and the language
php bin/magento maintenance:enable
php bin/magento setup:upgrade --keep-generated
php bin/magento maintenance:disable
Copied

We also recommend running php bin/magento cache:clean and php bin/magento cache:flush to ensure the site cache is cleared.

3

Enable module

Select the store settings and a new category what3words will be available.

Within the configuration page add the API Key.

We also recommend using a placeholder text with an example of what3words address to demonstrate to users the correct format they should follow to enter their own what3words. For example, eg. ///filled.count.soap

A new field will then be available on the site’s checkout page.

4

Add what3words address to the Address template

For the what3words address to appear on invoices, delivery labels, and packaging slips you will need to add the following attributes to the Customer Address Templates:

w3w → the chosen 3 words address returned by the address validation and saved in the database;

w3w_nearest → the value of the nearest place of the chosen 3 words address saved in the database. This value will be available only if the option Save nearest place is set to yes in the settings page of the what3words plugin.

w3w_coordinates → the coordinates of the chosen 3 word address saved in the database.  This value will be available only if the option Save coordinates is set to yes in the settings page of the what3words plugin.

To get to the Customer Address Templates of your Store:
“Stores”  > “Configuration”> “Customers” > “Customer Configuration” > “Address  Templates”

Add the following to each of the templates:

Text:
{{if w3w}}{{var w3w}}{{/if}}
{{if w3w_nearest}}{{var w3w_nearest}}{{/if}}
{{if w3w_coordinates}}{{var w3w_coordinates}}{{/if}}

Text One Line:
{{var w3w}},
{{var w3w_nearest}},
{{var w3w_nearest}},

HTML:
{{if w3w}}{{var w3w}}{{/if}}<br />
{{if w3w_nearest}}{{var w3w_nearest}}{{/if}}<br />
{{if w3w_coordinates}}{{var w3w_coordinates}}{{/if}}<br />

PDF:
{{if w3w}}{{var w3w}}{{/if}}|
{{if w3w_nearest}}{{var w3w_nearest}}{{/if}}|
{{if w3w_coordinates}}{{var w3w_coordinates}}{{/if}}|

5

How to obtain the what3words field using Stores API

In Magento, the what3words address attributes are stored in the customers’ shipping addresses of the Magento Customers and Orders REST APIs.

1. The API request to make to the Magento Customers REST API should be:
GET {{magento_base_url}}/rest/V1/customers/{{customer_id}}

The API response should be:

"addresses": [
   {
     "id": 3,
     "customer_id": 4,
      ...
     "custom_attributes": 
          [
              {
                    "attribute_code": "w3w",
                    "value": "filled.count.soap"
                },
                {
                    "attribute_code": "w3w_coordinates",
                    "value": "-0.195521 ,51.520847"
                },
                {
                    "attribute_code": "w3w_nearest",
                    "value": "Bayswater, London"
                }
           ]
        },
       ...
]
Copied

2. The API request to make to the Magento Orders REST API should be:
GET {{magento_base_url}}/rest/V1/orders?searchCriteria[currentPage]=0

The API response should be:

"extension_attributes": {
    "shipping_assignments": [
        {"shipping": {
            "address": {
                "address_type": "shipping",
                ...
                "extension_attributes": {
                    "w3w": "///filled.count.soap"
                }
            },
       ...
Copied

Additional settings

If you need to capture the coordinates for a three word address to help with delivery information, for example, you should check the Save coordinates checkbox.

The coordinates will added to your order and visible in your Sales page on Magento.

Note this uses an additional what3words API call to convert the what3words address to coordinates. Please ensure the tier you have signed up to covers the amount of usage you intend to do to avoid interruption of service.

If you need to capture the nearest place information for a three word address to help with delivery information, for example, you should check the Save nearest place checkbox.

The nearest place info will added to your order and visible in your Sales page on Magento.

You can override the default label for the address field by selecting this option and specifying the placeholder text. We recommend you use the default label value, as it provides your customers with an example of how to use the what3words Address Field.

You can override the default placeholder for the address field by selecting this option and specifying the placeholder text. We recommend you use the default placeholder value, as it provides your customers with an example of how to use the what3words Address Field.

In order to provide guidance to the customer, you can display a tooltip explainer and its question mark icon next to the what3words field.
This message will be displayed on the tooltip explainer:

By entering your 3 word address you make it much easier for our delivery partners to find you first time. To discover your 3 word address, visit what3words.com.

We provide a number of options for clipping the autosuggest results, limiting the addresses that can be validated and captured. You can clip suggestions to a number of countries by providing comma separated 2 digit ISO codes for each country you wish to clip to. This will ensure suggestions provided are clipped within the countries specified. You can also clip within a circle, a bounding box or a polygon.

N.B. – When providing multiple clippings the intersection of each polygon is what forms the suggestions provided when using the what3words Address Field.

For most checkouts we recommend skipping these options as the clip to country is automatically set when a user selects a country for their billing and/or shipping information as they select a country from the dropdown menu options in the checkout form.

In addition to country clipping, it is also possible to add focus to your what3words address suggestions by selecting the Autosuggest Focus feature. The AutoSuggest Focus feature uses the users’ location as focus for AutoSuggest to provide better suggestions if the store has the users’ location permission.

WebsiteAdd a 3 word address input fieldMagento

Related tutorials