Developer

All tutorials

Installing the Adobe Commerce (formerly Magento 2) extension

intermediate

The what3words Adobe Commerce (formerly 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, 2.4.6

1Get an API Key
Signup to create key
2Installation

The Adobe Commerce (formerly Magento 2) extension can be installed in 2 ways:

  1. Follow this installation guide;
  2. Use Composer and Packagist to ensure that all dependencies are installed along with the extension.

To add the 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, it will pull the latest release of this plugin from this what3words GitHub page

composer config repositories.what3words git https://github.com/what3words/magento2-w3w-plugin.git
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.

3Enable 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 the what3words address to demonstrate to users the correct format they should follow to enter their own what3words. For example, eg. ///filled.count.soap.

Find out how can you customise your extension in the Additional Settings section below.

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

4Add to 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_coordinates}},


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}}|
Copied
5Obtain what3words via 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
6Localising strings

The what3words extension allows you to modify default strings in your custom theme to load and use translation dictionaries. Learn more about locales, modifying strings, and how the application searches and applies translations in this tutorial page.

In case you are using a PWA (progressive app) in Magento. The way to translate the strings of our plugin is mentioned in this developer guide.

7Upgrade module

To update or upgrade the what3words module:

  1. Download the updated file from Marketplace or another extension developer. Take note of the module name and version.
  2. Export the contents to your application root directory.
  3. Since the Composer package exists for this module, run one of the following.

Update per module name:

composer update what3words/module-what3words
Copied

Update per version:

composer update what3words/module-what3words ^x.x.x
Copied

Run the following commands to upgrade, deploy, and clean the cache.

bin/magento setup:upgrade --keep-generated
bin/magento setup:static-content:deploy
bin/magento cache:clean
Copied
8Uninstall

In case you wish to uninstall the what3words Magento plugin that has been installed by composer, you can use the following command:

php bin/magento module:uninstall What3Words_What3Words --remove-data
Copied
9Troubleshooting

If you are using the Free plan and have enabled the save coordinates feature in your plugin settings, you are making convert-to-coordinate requests, which are not supported under the Free plan. You might encounter the following errors:

  • You should see an error similar to Transport error under the what3words address field at the checkout page.
  • In the network panel, look for Error 402: Payment Required. The response to this error is:

{
    "error": {
        "code": "QuotaExceeded",
        "message": "Quota Exceeded. Please upgrade your usage plan, or contact support@what3words.com"
    }
}
Copied

We are actively working on updating our plugins to prevent this error by disabling the save coordinates feature when the API key is registered under a Free plan.

For more information, visit our API plans page. If you need further assistance, contact support@what3words.com.

10Additional 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:

what3words addresses help our delivery partners find you first time. Find yours at what3words.com.

You can override the default Tooltip explainer text that you can see when you click on the question mark icon next to the what3words field.

You can override the default Error message when you enter an invalid what3words address in the input field.

You can set the HTML direction of your site using a right-to-left language on the configuration page.

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.

10Support

Have any questions?

We’re here to support you! If you have any questions while using what3words, get in touch with us by writing us an email at support@what3words.com

E-CommerceAdd a 3 word address input fieldAdobe Commerce (formerly Magento)

Related tutorials