The deCarta iPhone API provides a framework for rapid development of location-based iPhone applications. This framework uses Objective-C to provide modular fluid maps, panning, zooming, geocoding, reverse geocoding, point-of-interest searching, route calculation and pin overlays.
The deCarta iPhone API utilizes the deCarta DDS Web Services to perform much of its underlying functionality, so many of the iPhone API methods will perform client-server communications to perform the underlying functionality.
The following sections describe high-level features of the deCarta iPhone API, and provides some guidance as to the classes of the API that are used for performing key functions.
The deCarta iPhone API requires authentication with the clientName and clientPassword you received when registering on the deCarta Developer Zone (developer.decarta.com). These are distinct from the email address and password that you use to login to the deCarta Developer Zone.
The deCarta iPhone API provides a global structure called g_config, which is an instance of a deCartaConfigStruct structure. Valid credentials must be set in the properties of the g_config structure for API calls which require deCarta DDS Web Services to function.
Example:
//Set the configuration settings for the application using the globally-defined g_config structure: g_config.clientName=@""; g_config.clientPassword=@""; g_config.configuration_default=@"global-decarta"; g_config.configuration_high_res=@"global-decarta-hi-res"; g_config.transparentConfiguration=@"global-mobile-transparent"; g_config.host=@"http://ws.decarta.com/openls/openls";
//Configure additional API settings (see deCartaConfig.h for all options): g_config.LOG_LEVEL = LOG_LEVEL_DEBUG; //Sets logging level to "DEBUG". See enumerated type in deCartaLogger.h g_config.ENABLE_TILT = TRUE; g_config.ENABLE_ROTATE = TRUE; g_config.COMPASS_PLACE_LOCATION = 1;
The core of the deCarta iPhone API is the deCartaMapView class. This class provides methods for displaying and manipulating the map.
For an example of how to set up the map display, see the MapViewController in the sample application.
To center the map on a specified position, use the centerOnPosition: (deCartaMapView) method.
To zoom the map in or out one level, use zoomIn (deCartaMapView) or zoomOut (deCartaMapView), or use zoomTo: (deCartaMapView) to skip directly to a new zoom level.
To find the geographic position of an address, first store the free-form address as a deCartaFreeFormAddress, then use that address with the geocode:returnFreeFormAddress: (deCartaGeocoder) method to determine the geocoded location.
Free-form addresses permit flexible and forgiving user-input, which allows for incomplete or partial addresses, errors, and misspellings. The geocoder contacts the deCarta DDS Web Server to determine the best available matches for the free-form address.
When the response from the server is received, it will contain an array of deCartaGeocodeResponse objects, each which contain a deCartaStructuredAddress or deCartaFreeFormAddress (depending on what is requested when calling the geocode method), and a corresponding deCartaPosition indicating the geographic lat/lon position of that address. The application can then provide the user the option to select the best matching address from a list, in order to determine the desired position.
See the GeocodeViewController class in the sample application for an example.
To find the street address associated with a geographic position, first store the geographic position as a deCartaPosition object, then use that deCartaPosition with the reverseGeocode: (deCartaGeocoder) method to determine the reverse geocoded location.
The geocoder contacts the deCarta DDS Web Server to determine the reverse geocoded position. When the response from the server is received, it will contain a deCartaStructuredAddress object with the corresponding street address that best matches the position (it is an approximate, interpolated address). It will throw an exception if an appropriate address can not be determined.
See the MapViewController.doReverseGeocoding: method in the MapViewController class of the sample application for an example.
To search for a point of interest, first determine the center-location of the area to search (as a deCartaPosition), using the current location or using a geocoded address. Then, populate a deCartaPOISearchCriteria object with the search criteria for the point of interest search. Then use a deCartaPOIQuery object to perform the point of interest query using the criteria.
The deCartaPOIQuery contacts the deCarta DDS Web Server to find a list of best matches for the search criteria which are returned as an array of deCartaPOI objects.
See the POIViewController class in the sample application for an example.
Routing is crucial to all location-based services applications, both to visually display a route on a map and to provide turn-by-turn route instructions. The routing functionaliy is performed by the deCartaRouteQuery class.
When calculating a route, the query:routePreference: (deCartaRouteQuery) method requires an origin deCartaPosition, a destination deCartaPosition, and a deCartaRoutePreference object that has been configured with desired route query settings.
For route visualization, the deCartaRoutePreference.returnGeometry property should be set to YES. In this case, the returned deCartaRoute object will contain an array of deCartaPosition objects. These positions can then be used with the deCartaShape API for drawing a series of lines onto the map.
For turn-by-turn route instructions, the deCartaRoutePreference.returnInstructions property should be set to YES. In this case, the returned deCartaRoute object will contain an array of deCartaRouteInstruction objects, which provide the instructions at each maneuver.
See the RouteViewController class in the sample application for an example.
1.6.1
