Hi all,
I’ve just released Bubble’s first What3Words plugin, integrated into Google maps with the Drawing library included. Outlined below are all the details explaining how things work with a demo site created for anyone wanting to see the functionality provided by W3W.
PLUGIN
What3Words Advanced Plugin | Bubble
DEMO
https://paul-testing-4.bubbleapps.io/what_3_words
The plugin comes with 2 visual elements, one is the What3Words search bar and the other is a customized Google Map with the 3M square grid overlay (is seen when zoom level > 15). It also includes Google’s drawing & geometry libraries, making it possible to draw various shapes and polygons which can then be used to feed into the various features to retrieve details or fine tune the search results.
You’re able to convert any set of latitude/longitude coordinates into a 3 word address and vice versa (given you have the 3 word address), support is added for different languages and the API requests (both Action and Data) have been included. API requests can return both JSON and GEOJSON data where applicable.
WORKINGS
You’ll need to generate an API key over in What3Words first, then use this within the plugin settings as shown here. All fields should contain the same key with the exception of the Google maps API key.
The Google maps API key is offered through the plugin as a client side key, as a fall back if you ever need to use for any reason. It’s recommended that you put your key into your sites settings so it’s more secure. The plugin will only use the client side key when the Google maps API isn’t available or if you haven’t provided the key in your settings. You don’t need to enter it if you already have it setup through your settings.
Below outlines a list of all events, actions and documentation.
You can view the editor here: What3Words - Bubble Editor.
ELEMENTS
What3Words (search)
This visual element shows the w3w search bar.
-
Placeholder
Placeholder text to display. -
Initial value
Sets the initial value of the input element. It’s recommended that you always prepend the /// before the 3 word address. Example: ///oath.single.daisy -
Invalid address error message
Overwrites the error message with a custom value. -
Language
Allows you to add a preferred suggestion fall back language. This is a supported 3 word address language as an ISO 639-1 2 letter code. Only used when input value language cannot be determined. For a full list of 3 word address languages, you can run the “Get supported languages” action or “Available languages” API request. -
Auto suggest focus
Comma separated latitude/longitude of a point to focus the search results on. This is useful to focus results on a users location. Example: 51.521251,-0.203586 -
Clip to country
Restrict suggestions to a given country or comma separated list of countries. Example: GB,US -
Clip to bounding box
Restrict results to a bounding box, specified by coordinates. Values should specify a pair of SouthWest latitude/longitude coordinates, followed by a pair of NorthEast latitude/longitude coordinates to form the bounding area. SouthWest latitude should be less than or equal to NorthEast latitude and SouthWest longitude should be less than or equal to NorthEast longitude. Example value: 51.521, -0.343, 52.6, 2.3324 -
Clip to circle
Restrict results to a circle, specified by latitude, longitude and kilometres, where kilometres is the radius of the circle. For convenience, longitude is allowed to wrap around 180 degrees. For example 181 is equivalent to -179. Example value: 51.521, -0.343, 142 -
Clip to polygon
Restrict results to a polygon, specified by a comma-separated list of latitude and longitude pairs. The polygon should be closed, i.e. the first element should be repeated as the last element. The list should contain at least 4 entries and have no more than 25 pairs which is the limit. Example value: 51.521, -0.343, 52.6, 2.3324, 54.234, 8.343, 51.521, -0.343 -
Return coordinates
Makes an additional call to the What3Words API to obtain the coordinates for the selected 3 word address. This will trigger the “coordinates have changed” event and also populate both “Coordinates changed…” states with the returned latitude and longitude values. -
CSS style
Style the auto suggest search box by using custom CSS.
What3Words (map)
This visual element shows a Google map with the 3M square grid overlay and drawing options.
-
Info
A word address will take precedence over the latitude and longitude fields. The 3M square grid will be shown when the zoom level is greater than 15. -
Word address
Use a What3Word word address to show on the map, for example: darling.lion.race -
Latitude
Latitude coordinates -
Longitude
Longitude coordinates -
Initial zoom
Map zoom level -
Map type (Roadmap, Satellite, Hybrid, Terrain)
Map type to show. -
Disable UI
This disables any UI control buttons from the map. -
Grid color
Set the grid color.
DATA CELLS - (API endpoints)
Endpoints exist under both ‘Action’ and ‘Data’. The list below outlines all available API requests. You can refer to following link for details on all of these - API Reference Docs | what3words
-
Convert to 3 word address (2 versions to support json and geojson data)
This function will convert a latitude and longitude to a 3 word address, in the language of your choice. It also returns country, the bounds of the grid square, a nearby place (such as a local town) and a link to our map site.
-
Convert to coordinates (2 versions to support json and geojson data)
This function converts a 3 word address to a latitude and longitude. It also returns country, the bounds of the grid square, a nearest place (such as a local town) and a link to our map site.
-
Auto suggest
Auto suggest can take a slightly incorrect 3 word address and suggest a list of valid 3 word addresses. It has powerful features that can, for example, optionally limit results to a country or area, and prioritise results that are near to the user or within specific boundaries.
-
Available languages
Retrieves a list all available 3 word address languages, including the 2 letter code, English name and native name.
EVENTS
-
A What3Words (search) - error has occurred
Fires when any of the actions return an error, containing the error code and message.
-
A What3Words (search) - is ready
Fires when the What3Words API is ready.
-
A What3Words (search) - suggestion has been selected
Fires when a suggestion is selected from the dropdown. This event will also update the "Words" state with the selected 3 word address.
-
A What3Words (search) - suggestion has been changed
Fires when the suggestions displayed in the dropdown change.
-
A What3Words (search) - coordinates have changed
Only used when the "Return coordinates" option is set to Yes. Fires when coordinates change after a new valid 3 word address is selected. This event will also update the "Words" state with the selected 3 word address.
-
A What3Words (search) - input value has changed
Fired when the value entered into the input changes.
-
A What3Words (search) - input value is valid
Fired when a valid 3 word address has been selected from the suggestions.
-
A What3Words (search) - input value is not valid
Fired when a valid 3 word address has been selected from the suggestions.
-
A What3Words (map) - marker is clicked
Fires when a map marker is clicked.
-
A What3Words (map) - marker is hovered
Fires when input value is not a valid 3 word address.
ACTIONS
Element - What3Words (search)
-
Convert to 3 word address
Convert coordinates, expressed as latitude and longitude to a 3 word address.
-Latitude
Latitude coordinates
-Longitude
Longitude coordinates
-Language
A supported 3 word address language as an ISO 639-1 2 letter code. Defaults to en (english). For a full list of 3 word address languages, you can run the "Get supported languages" action or "Available languages" API request.
-
Get supported languages
Returns the currently supported languages. It will return the two letter code, and the name of the language both in that language and in English. -
Convert to coordinates
Convert a 3 word address to a position, expressed as coordinates of latitude and longitude.
-3 word address
The 3 word address to convert into coordinates, for example: darling.lion.race
-
Auto suggest words
Returns a list of potential correct 3 word addresses.
-3 word address
The full or partial 3 word address to obtain suggestions for. At minimum this must be the first two complete words plus at least one character from the third word. Example value: plan.clips.a
-Focus
This is a location field, specified as latitude and longitude (often where the user making the query is). If specified, the results will be weighted to give preference to those near the focus. Example value: 51.521251, -0.203586
-Clip to country
Restrict results to countries specified by a comma-separated list of ISO 3166-1 alpha-2 country codes. For example, to restrict to Belgium and the UK, use GB, BE (case insensitive).
-Clip to bounding box
Restrict results to a bounding box, specified by coordinates. Values should specify a pair of SouthWest latitude/longitude coordinates, followed by a pair of NorthEast latitude/longitude coordinates to form the bounding area. SouthWest latitude should be less than or equal to NorthEast latitude and SouthWest longitude should be less than or equal to NorthEast longitude. Example value: 51.521, -0.343, 52.6, 2.3324
-Clip to circle
Restrict results to a circle, specified by latitude, longitude and kilometres, where kilometres is the radius of the circle. For convenience, longitude is allowed to wrap around 180 degrees. For example 181 is equivalent to -179. Example value: 51.521, -0.343, 142
-Clip to polygon
Restrict results to a polygon, specified by a comma-separated list of latitude and longitude pairs. The polygon should be closed, i.e. the first element should be repeated as the last element. The list should contain at least 4 entries and have no more than 25 pairs which is the limit. Example value: 51.521, -0.343, 52.6, 2.3324, 54.234, 8.343, 51.521, -0.343
-Prefer land
Prefer results on land to those in the sea. This setting is on by default. Use false to disable this setting and receive more suggestions in the sea.
Element - What3Words (map)
-
Set marker
Adds the What3Words marker at a location specified.
-Word address
Use a What3Word word address to show on the map, for example: darling.lion.race
-Latitude
Latitude coordinates
-Longitude
Longitude coordinates
-Zoom
Map zoom level
-Go to marker
Go to the marker's position once it has been placed.
-Marker icon
Use your own customized marker. You should keep to a size no larger than 64 x 64px.
-Label
This is the label text seen when hovering over the marker. Leaving this field blank will default to showing the 3 word address.
-
Enable drawing tools
Enables the drawing tools.
-Color palette position (Top left,Top right,Bottom right,Bottom left)
Position of the color palette.
-
Disable drawing tools
Disables the drawing tools. -
Clear shape states
Allows you to clear the shape states.
-Clip to bounding box
Clears the clip to bounding state.
-Clip to circle
Clears the clip to circle state.
-Clip to polygon
Clears the clip to polygon state.
-Clip to polyline
Clears the clip to polyline state.
-Marker coordinates
Clears the marker coordinates state.
-
Go to coordinates
Shows the location on a map at the coordinates specified.
-Latitude
Latitude coordinates
-Longitude
Longitude coordinates
-
Remove marker
Removes a marker from the map.
-Marker Id
Use the marker Id that was specified when it was created.
-
Contains location
Checks to see whether a specified point (pair of latitude/longitude coordinates) falls inside or outside the boundaries of a polygon.
-Polygon coordinates
A comma-separated list of latitude and longitude pairs which make up the polygon. Example value: 51.521, -0.343, 52.6, 2.3324, 54.234, 8.343
-Point coordinates
A comma-separated pair of latitude and longitude coordinates that will be used to check whether they reside within the boundaries of the polygon.
-
Draw shape
Allows you to draw a shape onto the map using a set of coordinates.
-Shape type
This is the type of shape that you want to draw onto the map.
-Shape coordinates
Enter the coordinates which make up the shape. You should use the coordinates which are contained in the various Drawing states to make sure the format is correct.
-Fill color
Fill color for the shape.
-Editable
Make the shape editable.
-Draggable
Make the shape draggable.
-
Remove selected shape
Allows you to remove a currently selected shape.
EXPOSED STATES
Element - What3Words (search)
-
Latitude
Current latitude for an address.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Longitude
Current longitude for an address.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Language
Current language for a word address.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Country
Current country code for an address.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Map
URL to the What3Words website showing the current address.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Nearest place
Nearest place to the current address.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Square (north east) latitude
The north east (latitude) bounds of the 3M grid square.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Square (north east) longitude
The north east (longitude) bounds of the 3M grid square.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Square (south west) latitude
The south west (latitude) bounds of the 3M grid square.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Square (south west) longitude
The south west (longitude) bounds of the 3M grid square.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Words
Current word address.
Populated after running “Convert to 3 word address” or “Convert to coordinates” actions. -
Available languages (code)
A list of available languages (code).
Populated after running “Get supported languages” action. -
Available languages (name)
A list of available languages (name).
Populated after running “Get supported languages” action. -
Available languages (native name)
A list of available languages (native name).
Populated after running “Get supported languages” action. -
Error
This is populated with an error code and description if an error occurs. -
Auto suggest words
A list of auto suggested words that are returned from the “Auto suggest words” action.
Populated after running “Auto suggest words” action. -
Coordinates changed latitude
Contains the latitude address when coordinates have been changed due to a search result being selected. This state is only used used when the “Return coordinates” option is set to Yes. -
Coordinates changed longitude
Contains the longitude address when coordinates have been changed due to a search result being selected. This state is only used used when the “Return coordinates” option is set to Yes.
Element - What3Words (map)
-
Drawing clip to bounding box
Contains a set of coordinates that is generated when using the Rectangle drawing tool. -
Drawing clip to circle
Contains a set of coordinates that is generated when using the Circle drawing tool. -
Drawing clip to polygon
Contains a set of coordinates that is generated when using the Polygon drawing tool. -
Drawing clip to polyline
Contains a set of coordinates that is generated when using the Polyline drawing tool. -
Drawing marker coordinates
Contains a set of coordinates that is generated when using the Marker drawing tool. -
Clicked marker latitude
Contains the latitude for a clicked marker. -
Clicked marker longitude
Contains the longitude for a clicked marker. -
Clicked marker words
Contains the word address for a clicked marker. -
Clicked marker Id
Contains the marker Id for a clicked marker (if specified during creation).
Note: This state is populated when the “Set marker” action runs and it is cleared when the “Remove marker” action runs. -
Hovered marker latitude
Contains the latitude for a hovered marker. -
Hovered marker longitude
Contains the longitude for a hovered marker. -
Hovered marker words
Contains the word address for a hovered marker. -
Marker is hovered
Shows Yes when a marker is hovered and No when not. -
Set marker latitude
Contains the latitude when a marker is set. -
Set marker longitude
Contains the longitude when a marker is set. -
Set marker words
Contains the word address when a marker is set. -
Inside polygon
Shows Yes when a specific location is inside the boundaries of a polygon. This state is populated when running the “Contains location” action. -
Loading libraries
This will display Yes when the Google libraries are being loaded.
They’ll be a bunch of updates going forward to expand this plugin further. If anyone wants to see additional functionality put into it then by all means let me know!
Paul