What3Words Converter Plugin
Automatically convert What3Words addresses into standard geographic data including country codes, nearest places, and latitude/longitude coordinates using the official What3Words API.
The What3Words plugin for Flatfile automatically converts What3Words (W3W) addresses into standard geographic data. It listens for data commits, takes a W3W address from a specified field in a sheet, and uses the official What3Words API to fetch the corresponding country, nearest place, and latitude/longitude coordinates. The plugin then populates this information into other specified fields within the same record.
This is useful for any data import workflow where users provide locations using the What3Words system, and the application requires standard address components or geographic coordinates for mapping, logistics, or data normalization.
Installation
Install the plugin using npm:
Configuration & Parameters
The plugin is configured through the convertWhat3words
function, which accepts a configuration object with the following parameters:
Required Parameters
The key of the field in your sheet that contains the What3Words address to be converted.
The key of the field where the resulting country code (e.g., “GB”) will be stored.
The key of the field where the name of the nearest place (e.g., “London”) will be stored.
The key of the field where the resulting latitude coordinate will be stored.
The key of the field where the resulting longitude coordinate will be stored.
Optional Parameters
The slug of the specific sheet you want this plugin to apply to. If not provided, the plugin will apply to all sheets in the workbook that have a field matching the what3wordsField
configuration.
Usage Examples
Basic Usage
Apply the What3Words converter to a specific sheet:
Apply to All Sheets
Configure the plugin to run on all sheets by omitting the sheetSlug
option:
Troubleshooting
Conversions Not Working
- API Key: Verify that the
W3W_API_KEY
secret is correctly set in your Flatfile Space - Configuration: Double-check that the
sheetSlug
and all field keys (what3wordsField
,countryField
, etc.) in your configuration exactly match the schema of your sheet - Data Format: Ensure the field specified in
what3wordsField
contains valid, correctly formatted What3Words addresses
Error Messages
If the What3Words API call fails for any reason (e.g., invalid W3W address, network error, invalid API key), the plugin will add a record-level error to the what3wordsField
with the message “Invalid What3Words address”. This error will be visible to the user in the Flatfile UI.
Notes
Environment Setup
You must add your What3Words API key as an environment secret named W3W_API_KEY
in your Flatfile Space before using this plugin.
Default Behavior
- Sheet Targeting: When
sheetSlug
is not provided, the plugin applies to all sheets in the workbook that contain a field matching thewhat3wordsField
configuration - Event Trigger: The plugin operates using
bulkRecordHook
, which runs when the user clicks “Continue” or “Submit” on a sheet (during thecommit:created
event) - Processing: The conversion is not real-time as the user types; it occurs during the commit process
Error Handling
- The plugin processes records individually within a batch
- A failure on one record will not stop the processing of other records
- Errors are logged to the console for debugging purposes
- User-facing errors are attached directly to the record and field that caused the issue
Idempotency
The plugin processes records on each commit. If data is re-committed, the conversion will run again, potentially overwriting previously converted data.