HERE iOS SDK Developer's Guide

Geocoding and Reverse Geocoding

Geocoding and reverse geocoding APIs from the HERE iOS SDK allow application developers to offer search functionality for requesting NMAPlaceLocation information. Geocoding APIs resolve a free-formatted text query to an NMAGeoCoordinates, while reverse geocoding APIs resolve from an NMAGeoCoordinates to geographic data, such as NMAAddress.

NMAAddress provides textual address information including house number, street name, city, country, district and more. It encompasses everything about an address or a point on the map. The NMAPlaceLocation class represents an area on the map where additional attributes can be retrieved. These additional attributes include NMAAddress, unique identifier, label, location, access locations, and NMAGeoBoundingBox for the location.

The NMAGeocoder Interface

The NMAGeocoder interface represents a factory class used to instantiate location search requests. Two types of requests are available: NMAGeocodeRequest and NMAReverseGeocodeRequest.

The NMAGeocodeRequest Interface

The NMAGeocodeRequest interface represents an extended NMARequest. The NMAGeocodeRequest can be created using a combination of a search area and a free text query string. This is known as a "one-box" request. It returns NMAPlaceLocation results according to the specified search area and text query. You can specify a search area by providing a NMAGeoBoundingBox or a location with a search radius.

The following shows the methods used to create one-box requests:

NMAGeocodeRequest* request = [[NMAGeocoder sharedGeocoder] createGeocodeRequestWithQuery:string
            searchArea:geoBoundingBox
            locationContext:geoCoordinates];
NMAGeocodeRequest* request = [[NMAGeocoder sharedGeocoder] createGeocodeRequestWithQuery:string
            searchRadius:radius
            locationContext:geoCoordinates];

The preceding methods return an NMAGeocodeRequest object. To perform the request, call its startWithListener: method. The parameter of this method is an object which receives the request results; the object must implement the NMAResultListener protocol. Once a request is invoked, it can be canceled using the cancel method of NMARequest, which returns a BOOL value indicating whether the result was canceled successfully. If the NMAGeocodeRequest is successful, a list of NMAGeocodeResult objects is returned to the listener.

The following code example demonstrates how to use a NMAGeocodeRequest:


// Implementation of NMAResultListener
@interface NMAGeocodeTest : NSObject<NMAResultListener> {
}
@end
@implementation NMAGeocodeTest

// NMAResultListener protocol callback implementation
- (void)request:(NMARequest*)request
    didCompleteWithData:(id)data
    error:(NSError*)error
{
  if ( ( [request isKindOfClass:[NMAGeocodeRequest class]]) &&
    ( error.code == NMARequestErrorNone ) )
  {
    // Process result NSArray of NMAGeocodeResult objects
    [self processResult:(NSMutableArray *)data];
  }
  else
  {
    // Handle error
    ...
  }
}

- (void) startSearch
{
  NMAGeoCoordinates *topLeft =
    [[NMAGeoCoordinates alloc]
      initWithLatitude:52.537413 longitude:13.365641];
  NMAGeoCoordinates *bottomRight =
    [[NMAGeoCoordinates alloc]
      initWithLatitude:52.522428 longitude:13.39345];
  NMAGeoBoundingBox *boundingBox =
    [NMAGeoBoundingBox
      geoBoundingBoxWithTopLeft:topLeft bottomRight:bottomRight];

  NMAGeocodeRequest* request = [[NMAGeocoder sharedGeocoder]
  createGeocodeRequestWithQuery:@"100 INVALIDENSTRASSE"
            searchArea:boundingBox
            locationContext:nil];

  // limit the number of results to 10
  request.collectionSize = 10;

  NSError* error = [request startWithListener:self];
  if (error.code != NMARequestErrorNone)
  {
    // Handle request error
    ...
  }
}
@end

The NMAReverseGeocodeRequest interface

The NMAReverseGeocodeRequest interface represents an extended NMARequest used to retrieve NMAPlaceLocation data. The request is created using an NMAGeoCoordinates as shown below:

NMAGeocodeRequest* request = [[NMAGeocoder sharedGeocoder]
  createReverseGeocodeRequestWithGeoCoordinates:geoCoordinates];

The above method returns an NMAReverseGeocodeRequest object. Reverse geocode requests are used in the same way as regular geocode requests (described in the previous section), but the results are returned as an array of NMAReverseGeocodeResult objects.

The following example shows how to create and use an NMAReverseGeocodeRequest:


// Implementation of NMAResultListener
@interface NMAReverseGeocodeTest : NSObject<NMAResultListener> {
}
@end
@implementation NMAReverseGeocodeTest

// NMAResultListener protocol callback implementation
- (void)request:(NMARequest*)request
  didCompleteWithData:(id)data
  error:(NSError*)error
{
  if ( ( [request isKindOfClass:[NMAReverseGeocodeRequest class]]) &&
    ( error.code == NMARequestErrorNone ) )
  {
    // Process result NSArray of NMAReverseGeocodeResult objects
    [self processResult:(NSMutableArray *)data];
  }
  else
  {
    // Handle error
    ...
  }
}

- (void) startSearch
{
  // Instantiate an Address object
  NMAGeoCoordinates* vancouver = [[NMAGeoCoordinates alloc] initWithLatitude:49.2849 longitude:-123.1252];

  NMAReverseGeocodeRequest* request = [[NMAGeocoder sharedGeocoder] createReverseGeocodeRequestWithGeoCoordinates:vancouver];

  NSError* error = [request startWithListener:self];
  if (error.code != NMARequestErrorNone)
  {
    // Handle request error
    ...
  }
}

@end

For more information about the APIs introduced and demonstrated in this section, refer to the API Reference documentation.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.