iOS SDK

The what3words iOS SDK gives you programmatic access to what3words technology in your own iOS app. The iOS SDK allows the conversion of 3 word addresses to coordinates (forward geocoding), the conversion of coordinates to 3 word addresses (reverse geocoding), to obtain suggestions based on a full or partial 3 word address (AutoSuggest) and to determine the languages that the currently installed iOS SDK supports.

SDK Version

This page describes version 2 of the what3words iOS SDK; this is the latest version.

Get Started

To get a feel for geocoding with what3words, we recommend that you start with our RESTful API; this has all the main functional elements of our offline capable iOS SDK and you can be up and running in minutes. When you're ready to integrate what3words offline into your own iOS app, just get in touch with us at support@what3words.com and we'll get the ball rolling for you.

Installation

The what3words iOS SDK is distributed as a compressed archive. To install, simply uncompress the archive onto your development machine's filesystem.

.
├── lib
│   └── W3wIOSSDK.framework
├── sample
│   └── Example
│       └── what3words\ iOS\ demo
│           └── W3wIOSSDK.framework
└── w3w-data
    ├── wordlists
    ├── reversegeocode
    └── att
            

The lib/W3wIOSSDK.framework file should be referenced in your project's build files as a dependency.

Documentation

Complete and detailed documentation of the what3words iOS SDK, its public classes and methods are available in Appledoc format .

The remainder of this page provides an introduction to the concepts and useage of each of the iOS SDK's public methods.

SDK Initialisation

To initialise the what3words iOS SDK, instantiate a new instance of W3wIOSSDK.

                        
#import <W3wIOSSDK/W3wIOSSDK.h>

W3wIOSSDK *w3w = [[W3wIOSSDK alloc] init];
                        
                    

Forward Geocoding

The W3wIOSSDK.forwardGeocode class method converts a 3 word addresses to coordinates.

                        
#import <W3wIOSSDK/W3wIOSSDK.h>

W3wIOSSDK *w3w = [[W3wIOSSDK alloc] init];

W3wPosition *position = [w3w forwardGeocode:@"table.lamp.chair" outputLanguage:@"en"];
                        
                    

Reverse Geocoding

The W3wIOSSDK.reverseGeocode class method converts coordinates to a 3 word address.

                        
#import <W3wIOSSDK/W3wIOSSDK.h>

W3wIOSSDK *w3w = [[W3wIOSSDK alloc] init];

W3wLatLng *latLng = [[W3wLatLng alloc] initWithLat:42.2 lng:22.2];
W3wPosition *position = [w3w reverseGeocode:latLng language:@"en"];
                        
                    

AutoSuggest

The W3wIOSSDK.autosuggest class method returns a list of 3 word addresses based on user input and other parameters.

This method provides corrections for the following types of input error:

  • typing errors
  • spelling errors
  • misremembered words (e.g. singular vs. plural)
  • words in the wrong order

The autosuggest method determines possible corrections to the supplied 3 word address string based on the probability of the input errors listed above and returns a ranked list of suggestions. This method can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned.

Input 3 word address

You will only receive results back if the partial 3 word address string you submit contains the first two words and at least the first character of the third word; otherwise an error message will be returned.

Clipping and Focus

We provide various clip policies to allow you to specify a geographic area that is used to exclude results that are not likely to be relevant to your users. We recommend that you use the clip parameter to give a more targeted, shorter set of results to your user. If you know your user’s current location, we also strongly recommend that you use the focus to return results which are likely to be more relevant.

In summary, the clip policy is used to optionally restrict the list of candidate AutoSuggest results, after which, if focus has been supplied, this will be used to rank the results in order of relevancy to the focus.

Language

The lang parameter is mandatory for W3wIOSSDK.autosuggest(); we recommend that you set this according to the language of your user interface, or the browser/device language of your user. If your software or app displays 3 word addresses to users (in addition to accepting 3 words as a search/input) then we recommend you set the language parameter for this method to the same language that 3 word addresses are displayed to your users.

Results

A maximum of 10 AutoSuggest results may be returned, but you may choose to display fewer results to your user e.g. the first 3 or 5 (depending on your user interface). By default, 3 results will be returned. It is possible we may increase the number of results returned in the future, so if you choose to limit the list of results returned, we recommend that you choose to include e.g. the top 3/5/7 results rather than choose to exclude the bottom e.g. 8/9/10 results.

Clipping Policies

None default

W3wClipNone. No clipping takes place; this is the default.

Radius

W3wClipRadius. Clips to a radius of radius kilometers from the point specified as coords.

Bounding Box

W3wClipBBox. Clips to 3 word addresses that are fully contained inside a bounding box, specified by the northeast and southwest corner coordinates.

                        
#import <W3wIOSSDK/W3wIOSSDK.h>

W3wIOSSDK *w3w = [[W3wIOSSDK alloc] init];

W3wLatLng *latLng = [[W3wLatLng alloc] initWithLat:42.2 lng:22.2];
id<W3wClip> clip = [[W3wClipNone alloc] init];
NSArray *suggestions = [w3w autosuggest:@"table.lamp.chair" language:@"en" focus:latLng clip:clip];
                        
                    

StandardBlend

W3wIOSSDK.standardblend() method returns a blend of the three most relevant 3 word address candidates for a given location, based on a full or partial 3 word address.

The specified 3 word address may either be a full 3 word address or a partial 3 word address containing the first 2 words in full and at least 1 character of the 3rd word. The standardblend resource provides the search logic that powers the search box on map.what3words.com and in the what3words mobile apps.

Input 3 word address

You will only receive results back if the partial 3 word address string you submit contains the first two words and at least the first character of the third word; otherwise an error message will be returned.

Visualising StandardBlend

The what3words sample iOS app uses the standardBlend method to display candidate 3 word addresses. If the contents of the search box matches a partial 3 word address, detected by the regular expression ^\p{L}{4,}+\.\p{L}{4,}+\.\p{L}{1,}+$, then standardBlend will be invoked and any resulting candidate 3 word addresses displayed. The app also displays a relevant flag, keyed on the ISO 3166-1 alpha-2 country code that is returned by the SDK. For the app, we are using a flag set licensed from IconDrawer with the addition of two additional flags for tn and xk .

                        
#import <W3wIOSSDK/W3wIOSSDK.h>

W3wIOSSDK *w3w = [[W3wIOSSDK alloc] init];

// Initialise latLng with the return from LocationManager
W3wLatLng *latLng = [[W3wLatLng alloc] initWithLat:42.2 lng:22.2];
NSArray *suggestions = [w3w standardBlend:@"table.lamp.chair" focus:latLng language:@"en"];
                        
                    

Get Languages

The W3wIOSSDK.getLoadedLanguages() class method allows you to query the what3words SDK for the list of languages that the SDK currently supports.

                        
#import <W3wIOSSDK/W3wIOSSDK.h>

W3wIOSSDK *w3w = [[W3wIOSSDK alloc] init];

NSArray *languages = [w3w loadedLanguages];
                        
                    

Calculate Distance

The what3words iOS SDK provides two helper functions to calculate distances. W3wIOSSDK.distanceToPoint returns the distance between a 3 word address and a given point, whilst W3wIOSSDK.distanceBetweenPoints returns the distance between two points. Both of these methods return distance in meters.

                        
#import <W3wIOSSDK/W3wIOSSDK.h>

W3wIOSSDK *w3w = [[W3wIOSSDK alloc] init];

W3wLatLng *endPoint = [[W3wLatLng alloc] initWithLat:64.13577516756123 lng:-21.919784545898438];
double distance = [w3w distanceToPoint:@"index.home.raft" point:endPoint];

W3wLatLng *startPoint = [[W3wLatLng alloc] initWithLat:51.455905 lng:-0.341492];
distance = [w3w distanceBetweenPoints(startPoint, endPoint:endPoint];
                        
                    

Sample Application

The what3words SDK provides a sample Objective-C iOS app, located in [sdk-installation-path]/sample and can be compiled and run from within Xcode .

The sample app demonstrates how to initialise the what3words iOS SDK, to forward geocode a 3 word address to coordinates, to reverse geocode coordinates to a 3 word address and how to create a search box that uses the SDK's Standard Blend method to obtain the most relevant 3 word address candidates from a search string.