API

Methods

Objects

What3words wrapper methods

Harmony RightAddress wrapper methods for what3words. For error section.

The API Specification, also available on each method below - it requires valid username and password.

suggest Find a list of potential correct 3 word addresses.
3wa Convert a latitude and longitude to a 3 word address, in the language of your choice.
coordinates A 3 word address as a string. It must be three words separated with dots or a Japanese middle dot character.
gridsection Find a section of the 3m x 3m What3Words grid for a bounding box.
languages Retrieves a list of all available 3 word languages, including the ISO 3166-1 alpha-2 2 letter code, english name and native name.

suggest

Takes a slightly incorrect 3 word address and suggest a list of valid 3 word addresses. It needs the first two words plus at least the first character of the third word to produce suggestions. This method provides corrections for misspelled words (including plural vs singular), and words being in the wrong order.

Optionally, to dramatically improves results, use clipping to narrow down the possibilities and limit results to: one or more countries, or a geographic area (a circle, box or polygon). To improve results even further, use focus to get the return result closer to the user's current location.

It returns the top 3 results by default. You can request to return maximum 100 results.

Resource URL


    GET    https://hosted.mastersoftgroup.com/w3w/api/v1/suggest

Request Parameters (GET):

input * required

Type: String A full or partial 3 word address. A partial 3 word address must contain at least the first two words and first character of the third word. Example: dice.back.lowe.

nResults

Type: String The number of return results. Maximum is 100 results. If greater than this is specified, the result will be truncated to the maximum.

focus

Type: String A location, specified as latitude,longitude (often where the user making the query is). If specified, the results will be weighted to give preference to those near the focus. For convenience, longitude is allowed to wrap around the 180 line, so 361 is equivalent to 1. Example: -33.864422,151.208285.

nFocusResults

Type: String The number of results within the results set which will have a focus (must be <= nResults). Default to nResults. This allows a mix of focused and unfocused results to give a 'blend' of the two. For example nFocusResults=1 will return just one focused result and the rest unfocused.

clipToCountry

Type: String Restrict to only return results inside the countries specified by comma-separated list of uppercase ISO 3166-1 alpha-2 country codes (case-insensitive, must be two a-z letters). Example: AU,NZ to restrict to Australia and New Zealand.

clipToBoundingBox

Type: String Restrict results to a bounding box, specified by coordinates: south_lat,west_lng,north_lat,east_lng, where south_lat <= north_lat, west_lng <= east_lng. Example: 51.521,-0.343,52.6,2.3324. Lng is allowed to wrap, so can specify bounding boxes which cross the ante-meridian, example: -4,178.2,22,195.4.

clipToCircle

Type: String Restrict the results to a circle, specified by lat,lng,kilometers, where kilometers is the radius of the circle. Longitude is allowed to wrap around 180 degrees, example 181 is equivalent to -179. Example: 51.521,-0.343,142.

clipToPolygon

Type: String Restrict results to a polygon, specified by a comma-separated list of lat,lng pairs. The polygon should be closed, i.e. the first element should be repeated as the last element, also the list should contain at least 4 entries. It is currently limited to accept up to 25 pairs. Example: 51.521,-0.343,52.6,2.3324,54.234,8.343,51.521,-0.343.

inputType

Type: String Specify voice input mode. Can be text (default), vocon-hybrid, nmdp-asr, or generic-voice.

language

Type: String For normal text input, specified a fallback language, which will help if the input is particularly messy. If specified, this parameter must be a supported 3 word address language as an ISO 639-1 2 letter code. Example: fr. It is mandatory for voice input.

preferLand

Type: String This setting is on by default, which will prefer results on land to those in the sea. Use false to disable this setting and receive more suggestions in the sea.

Request

Lookup the top 3 of 3words addresses using this partial 3words address, filtered by these countries, and ordered by the nearest to this latitude and longitude location:


    https://hosted.mastersoftgroup.com/w3w/api/v1/suggest?input=dice.back.lowe&clipToCountry=AU,NZ&focus=-33.864422,151.208285&nResults=3

Response

The response body is an HostedW3WResponse object:


    {
        "status": 200,
        "code": "OK",
        "timestamp": "2020-11-16 09:22:34",
        "w3w": {
            "suggestions": [
                {
                    "country": "AU",
                    "nearestPlace": "Sydney, New South Wales",
                    "words": "dice.back.lowest",
                    "distanceToFocusKm": 0,
                    "rank": 1,
                    "language": "en"
                },
                {
                    "country": "AU",
                    "nearestPlace": "Dolans Bay, New South Wales",
                    "words": "dive.backs.lows",
                    "distanceToFocusKm": 23,
                    "rank": 2,
                    "language": "en"
                },
                {
                    "country": "AU",
                    "nearestPlace": "Bexley, New South Wales",
                    "words": "rice.back.lies",
                    "distanceToFocusKm": 13,
                    "rank": 3,
                    "language": "en"
                }
            ]
        }
    }

3wa

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 what3words map site.

Resource URL


    GET    https://hosted.mastersoftgroup.com/w3w/api/v1/3wa

Request Parameters (GET):

coordinates * required

Type: String Coordinates as a comma-separated string of latitude and longitude. Example: -33.864422,151.208285.

language

Type: String A supported 3 word address language as an ISO 639-1 2 letter code. Default to en (english). For a full list of 3 word address languages, see languages method.

Request

Convert to a 3words address for this latitude,longitude coordinates:


    https://hosted.mastersoftgroup.com/w3w/api/v1/3wa?coordinates=-33.864422,151.208285

Response

The response body is an HostedW3WResponse object:


    {
        "status": 200,
        "code": "OK",
        "timestamp": "2020-11-16 11:50:05",
        "w3w": {
            "country": "AU",
            "square": {
                "southwest": {
                    "lng": 151.208268,
                    "lat": -33.864435
                },
                "northeast": {
                    "lng": 151.208301,
                    "lat": -33.864408
                }
            },
            "nearestPlace": "Sydney, New South Wales",
            "coordinates": {
                "lng": 151.208285,
                "lat": -33.864422
            },
            "words": "dice.back.lowest",
            "language": "en",
            "map": "https://w3w.co/dice.back.lowest"
        }
    }

coordinates

Convert a 3 word address to a latitude and longitude. The 3 word address must be three words separated with dots or prefixed with ///. It also returns country, the bounds of the grid square, a nearest place (such as a local town) and a link to what3words map site.

There is an option to lookup addresses using these latitude, longitude and country from this 3word address conversion result. This reverse geocode will use GNAF source of truth for country AU (Australia) or NZAD source of truth for country NZ (New Zealand), to return 20 nearest addresses to these coordinates.

Resource URL


    GET    https://hosted.mastersoftgroup.com/w3w/api/v1/coordinates

Request Parameters (GET):

words * required

Type: String A 3 word address as a string. It must be three words separated with dots or a Japanese middle dot character. Optionally the 3 word address can be prefixed with ///, which would be encoded as %2F%2F%2F. Example: index.home.raft or ///dice.back.lowest.

reverseGeocode

Type: String Use the coordinates and country from the 3 word address conversion to reverse geocode using GNAF source of truth for country AU and NZAD source of truth for country NZ. It returns 20 nearest results to these coordinates. This setting is disabled by default. Use true to enable this setting.

Request

Convert to latitude, longitude coordinates for this 3 words address:


    https://hosted.mastersoftgroup.com/w3w/api/v1/coordinates?words=dice.back.lowest

Response

The response body is an HostedW3WResponse object:


    {
        "status": 200,
        "code": "OK",
        "timestamp": "2020-11-17 12:05:49",
        "w3w": {
            "country": "AU",
            "square": {
                "southwest": {
                    "lng": 151.208268,
                    "lat": -33.864435
                },
                "northeast": {
                    "lng": 151.208301,
                    "lat": -33.864408
                }
            },
            "nearestPlace": "Sydney, New South Wales",
            "coordinates": {
                "lng": 151.208285,
                "lat": -33.864422
            },
            "words": "dice.back.lowest",
            "language": "en",
            "map": "https://w3w.co/dice.back.lowest"
        }
    }

Convert to latitude,longitude coordinates for this 3 words address and also lookup addresses for these latitude, longitude and country:


    https://hosted.mastersoftgroup.com/w3w/api/v1/coordinates?words=dice.back.lowest&reverseGeocode=true

Response

The response body is an HostedW3WResponse object:


    {
        "status": 200,
        "code": "OK",
        "timestamp": "2020-11-17 12:20:28",
        "w3w": {
            "country": "AU",
            "square": {
                "southwest": {
                    "lng": 151.208268,
                    "lat": -33.864435
                },
                "northeast": {
                    "lng": 151.208301,
                    "lat": -33.864408
                }
            },
            "nearestPlace": "Sydney, New South Wales",
            "coordinates": {
                "lng": 151.208285,
                "lat": -33.864422
            },
            "words": "dice.back.lowest",
            "language": "en",
            "map": "https://w3w.co/dice.back.lowest"
        },
        "hra": [
            {
                "attributes": {
                    "GNAFGroupPID": "Nsw2813775",
                    "GNAFPIDPosition": "Doorstop",
                    "ParcelID": "1//dp628553",
                    "GNAFReliability": "2",
                    "GNAFPointPID": "Gansw717802735",
                    "GNAFPID": "Gansw717802735",
                    "GNAFConfidence": "1",
                    "GNAFLocalityPID": "Nsw3749",
                    "Latitude": "-33.86440996",
                    "Longitude": "151.20828704",
                    "GeocodeLevel": "7",
                    "MeshblockId": "10743110000"
                },
                "buildingName": "",
                "country": null,
                "eid": "6721786C850D16E4CEEE6DD98DA869B2DEC0193E94A58D2501BF03DF7F080A01",
                "flatUnitNumber": "",
                "flatUnitType": "",
                "floorLevelNumber": "1",
                "floorLevelType": "L",
                "fullAddress": "L 1 20 Bond Street, Sydney NSW 2000",
                "id": "GANSW717802735",
                "lotNumber": "",
                "postal": "",
                "postalNumber": "",
                "postalType": "",
                "postcode": "2000",
                "street": "Bond Street",
                "street2": null,
                "streetName": "Bond",
                "streetNumber": "20",
                "streetSuffix": "",
                "streetType": "Street",
                "subLocality": null,
                "subdwelling": "L 1"
            },
            {
                "attributes": {
                    "GNAFGroupPID": "Nsw2813775",
                    "GNAFPIDPosition": "Doorstop",
                    "ParcelID": "1//dp628553",
                    "GNAFReliability": "2",
                    "GNAFPointPID": "Gansw717802749",
                    "GNAFPID": "Gansw717802749",
                    "GNAFConfidence": "1",
                    "GNAFLocalityPID": "Nsw3749",
                    "Latitude": "-33.86440996",
                    "Longitude": "151.20828704",
                    "GeocodeLevel": "7",
                    "MeshblockId": "10743110000"
                },
                "buildingName": "",
                "country": null,
                "eid": "1C2993914641C68F0B0673D5E160E71C52DF85F4C7658866CBAB916A0B4C56BD",
                "flatUnitNumber": "",
                "flatUnitType": "",
                "floorLevelNumber": "2",
                "floorLevelType": "L",
                "fullAddress": "L 2 20 Bond Street, Sydney NSW 2000",
                "id": "GANSW717802749",
                "lotNumber": "",
                "postal": "",
                "postalNumber": "",
                "postalType": "",
                "postcode": "2000",
                "street": "Bond Street",
                "street2": null,
                "streetName": "Bond",
                "streetNumber": "20",
                "streetSuffix": "",
                "streetType": "Street",
                "subLocality": null,
                "subdwelling": "L 2"
            },
            {
                ....
            }
        ]
    }

Convert to latitude,longitude coordinates for this 3 words address with reverseGeocode but the address service is not running:


    https://hosted.mastersoftgroup.com/w3w/api/v1/coordinates?words=dice.back.lowest&reverseGeocode=true

Response

The response body is an HostedW3WResponse object:


    {
        "status": 200,
        "code": "OK",
        "messages":["failed to connect to address service"],
        "timestamp": "2020-11-17 12:20:28",
        "w3w": {
            "country": "AU",
            "square": {
                "southwest": {
                    "lng": 151.208268,
                    "lat": -33.864435
                },
                "northeast": {
                    "lng": 151.208301,
                    "lat": -33.864408
                }
            },
            "nearestPlace": "Sydney, New South Wales",
            "coordinates": {
                "lng": 151.208285,
                "lat": -33.864422
            },
            "words": "dice.back.lowest",
            "language": "en",
            "map": "https://w3w.co/dice.back.lowest"
        },
        "hra": []
    }

Convert to latitude,longitude coordinates for this 3 words address with reverseGeocode but not authorized to access the address service:


    https://hosted.mastersoftgroup.com/w3w/api/v1/coordinates?words=pure.larger.could&reverseGeocode=true

Response

The response body is an HostedW3WResponse object:


    {    
        "status": 200,
        "code": "OK",
        "messages":["Access is denied"],
        "timestamp": "2020-11-17 12:20:28",
        "w3w": {
           "country": "NZ",
            "square": {
                "southwest": {
                    "lng": 174.795001,
                    "lat": -41.216014
                },
                "northeast": {
                    "lng": 174.795037,
                    "lat": -41.215987
                }
            },
            "nearestPlace": "Khandallah, Wellington",
            "coordinates": {
                "lng": 174.795019,
                "lat": -41.216001
            },
            "words": "pure.larger.could",
            "language": "en",
            "map": "https://w3w.co/pure.larger.could"
        },
        "hra": []
    }

gridsection

Find a section of the 3m x 3m what3words grid for a bounding box. The bounding box is specified by lat,lng,lat,lng as south,west,north,east. By default the data format type is in JSON. You can request the grid in GeoJSON format, making it very simple to display on a map.

Resource URL


    GET    https://hosted.mastersoftgroup.com/w3w/api/v1/gridsection

Request Parameters (GET):

boundingBox * required

Type: String Bounding box as a lat,lng,lat,lng, for which the grid should be returned. The requested box must not exceed 4km from corner to corner. Latitudes must be >= -90 and <= 90, but longitudes are allowed to wrap around 180. Example: 52.207988,0.116126,52.208867,0.117540. To specify a bounding-box crossed the anti-meridian, use longitude > 180, example: 50.0,179.995,50.01,180.0005.

format

Type: String Data format type, can be either json (default) or geojson. You can request the grid in GeoJSON format, making it very simple to display on a map.

Request

Find a section of the 3m x 3m what3words grid for these bounding box coordinates in JSON format:


    https://hosted.mastersoftgroup.com/w3w/api/v1/gridsection?boundingBox=-33.864435,151.208268,-33.864408,151.208301

Response

The response body is an HostedW3WResponse object:


    {
        "status": 200,
        "code": "OK",
        "timestamp": "2020-11-17 01:27:46",
        "w3w": {
            "lines": [
                {
                    "start": {
                        "lng": 151.208268,
                        "lat": -33.86440815006468
                    },
                    "end": {
                        "lng": 151.208301,
                        "lat": -33.86440815006468
                    }
                },
                {
                    "start": {
                        "lng": 151.20826838139777,
                        "lat": -33.864435
                    },
                    "end": {
                        "lng": 151.20826838139777,
                        "lat": -33.864408
                    }
                },
                {
                    "start": {
                        "lng": 151.20830085736554,
                        "lat": -33.864435
                    },
                    "end": {
                        "lng": 151.20830085736554,
                        "lat": -33.864408
                    }
                }
            ]
        }
    }

Find a section of the 3m x 3m what3words grid for these bounding box coordinates in GeoJSON format:


    https://hosted.mastersoftgroup.com/w3w/api/v1/gridsection?boundingBox=-33.864435,151.208268,-33.864408,151.208301&format=geojson

Response

The response body is an HostedW3WResponse object:


    {
        "status": 200,
        "code": "OK",
        "timestamp": "2020-11-17 01:34:27",
        "w3w": {
            "features": [
                {
                    "geometry": {
                        "coordinates": [
                            [
                                [
                                    151.208268,
                                    -33.86440815006468
                                ],
                                [
                                    151.208301,
                                    -33.86440815006468
                                ]
                            ],
                            [
                                [
                                    151.20826838139777,
                                    -33.864435
                                ],
                                [
                                    151.20826838139777,
                                    -33.864408
                                ]
                            ],
                            [
                                [
                                    151.20830085736554,
                                    -33.864435
                                ],
                                [
                                    151.20830085736554,
                                    -33.864408
                                ]
                            ]
                        ],
                        "type": "MultiLineString"
                    },
                    "type": "Feature",
                    "properties": {}
                }
            ],
            "type": "FeatureCollection"
        }
    }

languages

Retrieves a list of all available 3 word languages, including the ISO 3166-1 alpha-2 2 letter code, english name and native name.

Resource URL


    GET    https://hosted.mastersoftgroup.com/w3w/api/v1/languages

Response

The response body is an HostedW3WResponse object:


    {
        "status": 200,
        "code": "OK",
        "timestamp": "2020-11-17 02:45:39",
        "w3w": {
            "languages": [
                {
                    "code": "de",
                    "name": "German",
                    "nativeName": "Deutsch"
                },
                {
                    "code": "no",
                    "name": "Norwegian",
                    "nativeName": "Norsk"
                },
                {
                    "code": "fi",
                    "name": "Finnish",
                    "nativeName": "Suomi"
                },
                {
                    ....
                }
            ]
        }
    }

Error

Examples when encountered HTTP non-200 error.

Request

Invoked API call with invalid username and password:

Response

The response body is an HostedW3WResponse object:


    {
        "status": 401,
        "code": "UNAUTHORIZED",
        "messages": [
            "Full authentication is required to access this resource"    
        ],
        "timestamp": "2020-11-17 12:00:10"
    }

Invoked suggest API with invalid clipToCountry:


    https://hosted.mastersoftgroup.com/w3w/api/v1/suggest?input=dice.back.lowe&clipToCountry=ABCDE

Response

The response body is an HostedW3WResponse object:


    {
        "status": 400,
        "code": "BadClipToCountry",
        "messages": [
            "Countries are specified as a comma separated list of uppercase ISO 3166-1 alpha-2 country codes, such as US,CA"    
        ],
        "timestamp": "2020-11-17 12:01:57"
    }

Invoked 3wa API with invalid coordinates:


    https://hosted.mastersoftgroup.com/w3w/api/v1/3wa?coordinates=ABCDE&language=en

Response

The response body is an HostedW3WResponse object:


    {
        "status": 400,
        "code": "BadCoordinates",
        "messages": [
            "coordinates must be two comma separated lat,lng coordinates"    
        ],
        "timestamp": "2020-11-17 12:28:02"
    }