Inherits from NSObject
Declared in OSGeocoder.h

Overview

OSGeocoder provides an interface to lookup positions based on place names, postcodes, grid references, roads, or any combination thereof.

It operates on either/both an offline database which is provided with the SDK or Ordnance Survey online services

OSGeocoder is not thread-safe, and is not reentrant. It must only be called from a single thread, and only one geocoding operation can be run at any one time. Clients should use cancelGeocode to cancel online searches, and not issue requests while isGeocoding returns YES.

The search always returns a (possibly empty) array of objects derived from OSPlacemark objects. Any matching roads are returned as OSRoad objects.

A search of type OSGeocodeTypeOnlinePostcode or OSGeocodeTypeOnlineGazetteer will use the appropriate Ordnance Survey online service to fetch results.

A search of type OSGeocodeTypeGazetteer will return matching place names. These will be ordered by the type of place; Cities will be returned before Towns, and Towns before other features.

A search of type OSGeocodeTypeGridReference will treat the search term as an OS Grid Reference. It will return up to one result. A valid search term consists of two letters as per the [OS National Grid Square convention][https://www.ordnancesurvey.co.uk/oswebsite/gps/information/coordinatesystemsinfo/guidetonationalgrid/page9.html] followed by 0,2,4,6,8 or 10 digits. Invalid search terms (not matching this format, or containing invalid letter sequences) will return no results.

A search of type OSGeocodeTypeRoad will return roads matching the search term. If none are found, then the search term will be split into a road and a location. If a comma is present in the search term, the split will be made there, otherwise the split is carried out automatically. The search will then return roads near matching locations.

OSGeocoder allows searches to be carried out with a range. The behaviour of this range varies.

A search over multiple types (for example Gazetteer and Road) will search for entries of the specified types that match the search string. These results will be ordered by result type.

The range field is honoured for searches of type OSGeocodeTypeGazetteer and OSGeocodeTypeRoad, but ignored for all other types of search. A search combining multiple types will honour the range field where it can, but will apply the range individually to each result set, so a combined search with a range of

    (NSRange){0,100}

may return 100 gazetteer entries AND 100 roads.

Tasks

Properties

geocoding

Indicates whether a geocoding operation is in progress.

@property (nonatomic, assign, readonly, getter=isGeocoding) bool geocoding

Declared In

OSGeocoder.h

Instance Methods

cancelGeocode

Cancel an existing geocoding operation

- (void)cancelGeocode

Declared In

OSGeocoder.h

geocodeString:type:inBoundingRect:withRange:completionHandler:

type of search to execute

- (void)geocodeString:(NSString *)s type:(OSGeocodeType)type inBoundingRect:(OSGridRect)rect withRange:(NSRange)range completionHandler:(OSGeocoderCompletionHandler)completionHandler

Parameters

type

type of search to execute

rect

limiting rectangle for search. To search the entire area, specify either OSGridRectNull or OSNationalGridBounds. This parameter is ignored for online searches

range

specifies number (and offset) of results to return. This will be applied individually to each

    type of search, so a range of {0,100} may return more than 100 results on combined gazetteer/road searches. 
    The range is ignored for postcode and grid reference searches.

To return ALL results, set range to

{NSNotFound, 0}
completionHandler

block to call with the results.

Callbacks for offline searches will be made synchronously, while callbacks for online searches will be made asynchronously on the caller thread. A search which comprises both offline 
and online types may results in up to two callbacks, one synchronous, and one asynchronous.

If no results are found, completionHandler will be called once (even for combiend offline/online searches) with a non-nil error indicating the problem. 

The completionHandler MUST NOT start a search before returning if the error is OSGeocoderErrorCancelled.

Declared In

OSGeocoder.h

initWithDatabase:

Initialise the Geocoder in offline only mode

- (id)initWithDatabase:(NSString *)path

Declared In

OSGeocoder.h

initWithDatabase:apiKey:openSpacePro:

Initialise the OSGeocoder

- (id)initWithDatabase:(NSString *)path apiKey:(NSString *)key openSpacePro:(bool)pro

Parameters

path

location of a database file to use.

apiKey

key for online searches.

openSpacePro

indicates if online searches should be made against the pro service

Discussion

  • If both path and apiKey are nil, then results will only be returned for OSGeocodeTypeGridReference
  • If path is nil, searches for offline types OSGeocodeTypeGazetteer, OSGeocodeTypePostCode, and OSGeocodeTypeRoad will return no results.
  • If apiKey is nil, searches for online types OSGeocodeTypeOnlineGazetteer and OSGeocodeTypeOnlinePostCode will return no results.

Declared In

OSGeocoder.h