Forum Academy Marketplace Showcase Pricing Features

[PLUGIN] - What3Words Advanced + Google Map (drawing/geometry)

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

1 Like

Nice work, and great documentation - I think this may come in handy for a feature down the road!

Thanks Andy!
I do try to be as thorough as possible!

Excelent Paul!
I´m new in Bubble and I was looking for map features.
Is it possible to save a polygon in a data type? and is there a function where I can verifify if a given geographic point is in a given polygon?

Thanks

Mario

Hi @mario.harada

Thanks! You can save the polygon data to your database since it’s just a comma separated Text state containing the set of coordinates which make up that shape (this applies to all shapes).

There isn’t a function (or action) included that will tell you if a specific set of coordinates were inside a polygon but I suspect I could add that for you. Would you just want it to return a Yes/No?

Hi Paul,

I ll set your plugin and Yes, I just want a yes/no for point in polygon.

thank You very much

Mário

No probs will give you a shout when it’s done.

@mario.harada

There’s a new action added called Contains location and it updates a corresponding state called Inside polygon with a simple Boolean (yes/no) value.

That action takes a set of polygon coordinates and a set of latitude/longitude coordinates.
You can get these from a couple of the Drawing states.

If you take a look at the demo and enable the drawing tools, you can draw a polygon and then drop a marker, you’ll see an icon appear on the left of the map. Click that icon and it will tell you if that dropped marker falls inside or outside the boundaries of the polygon. You can move them around click the icon again to retest.

I’ve added the additional details above to the documentation.

Hope that helps!
Paul

This will help me a lot! Thank you Paul

1 Like