API Documentation
API Documentation
This guide will take you through the process of integrating CedarMaps into your iOS application.
All the mentioned methods and tools in this document are tested on Xcode v9.3.
CedarMaps is available through CocoaPods. To install
it, simply add the following line to your Podfile and run pod install.
pod 'CedarMaps'
If your app needs to access location services, add a description usage for NSLocationWhenInUseUsageDescription in your app's Info.plist:
<key>NSLocationWhenInUseUsageDescription</key>
<string>THE REASON OF REQUESTING LOCATION</string>
To use CedarMaps tiles and methods, you need a pair of clientID and clientSecret which is used at the first step of initialising the SDK.
AppDelegate's applicationDidFinishLaunchingWithOptions: is a good place to initialize CedarMaps.
[[CSMapKit sharedMapKit] setCredentialsWithClientID:@"CLIENT_ID" clientSecret:@"CLIENT_SECRET"];
CSMapKit.shared.setCredentialsWithClientID("CLIENT_ID", clientSecret: "CLIENT_SECRET")
If you've received an API Base URL, you can set it on CSMapKit shared object:
[[CSMapKit sharedMapKit] setAPIBaseURL:@"API_BASE_URL"];
CSMapKit.shared.setAPIBaseURL("API_BASE_URL")
CedarMaps SDK is based on Mapbox iOS SDK v4.0 and provides extra API methods over Mapbox.
For more information about how to use Mapbox components and methods such as Adding Markers, Showing Current Location, etc., please see Mapbox Getting Started.
If you want to use CedarMaps tiles, there's one extra step to do. After doing the following snippet, you can use an instance of CSMapView, which is a subclass of Mapbox MGLMapView, in either Storyboard or code; they shall not be used interchangeably.
[[CSMapKit sharedMapKit] prepareMapTiles:^(BOOL isReady, NSError * _Nullable error) {
}];
CSMapKit.shared.prepareMapTiles { isSuccesful, error in
}
You can set various style URLs to instances of CSMapView:
mapView.styleUrl = "STYLE_URL"
// Light Vector (Default): "https://api.cedarmaps.com/v1/styles/cedarmaps.light.json"
// Dark Vector: "https://api.cedarmaps.com/v1/styles/cedarmaps.dark.json"
// Raster: "https://api.cedarmaps.com/v1/tiles/light.json"
Make sure to use your base URL if you have one.
In addition to using MapView, you can use CedarMaps API to retrieve location based data and street search.
All API calls are asynchronous; they don't block the Main Queue. The completion handlers are all called on the Main Queue.
You can also consult CSMapKit.h for detailed info on all of our methods. Some of the main methods are mentioned below.
For finding a street or some limited POIs, you can easily call geocode methods.
- (void)geocodeAddressString:(nonnull NSString *)addressString
inBoundingBox:(nonnull CSBoundingBox *)boundingBox
withType:(CSPlacemarkType)type
limit:(NSInteger)limit
completionHandler:(nonnull CSForwardGeocodeCompletionHandler)completionHandler;
open func geocodeAddressString(_ addressString: String, in boundingBox: CSBoundingBox, with type: CSPlacemarkType, limit: Int, completionHandler: @escaping CSForwardGeocodeCompletionHandler)
More advanced street searches are available in the sample app.
You can retrieve data about a location by using Reverse Geocode API.
- (void)reverseGeocodeLocation:(nonnull CLLocation *)location
completionHandler:(nonnull CSReverseGeocodeCompletionHandler)completionHandler;
open func reverseGeocodeLocation(_ location: CLLocation, completionHandler: @escaping CSReverseGeocodeCompletionHandler)
This method calculates the direction between points. It can be called with up to 50 different pairs in a single request.
- (void)calculateDirections:(nonnull NSArray<CSRoutePair *> *)routePairs withCompletionHandler:(nonnull CSDirectionCompletionHandler)completionHandler;
open func calculateDirections(_ routePairs: [CSRoutePair], withCompletionHandler completionHandler: @escaping CSDirectionCompletionHandler)
This method calculates the distance between points in meters. It can be called with up to 15 different points in a single request.
- (void)calculateDistance:(nonnull NSArray<CSRoutePair *> *)routePairs withCompletionHandler:(nonnull CSDirectionCompletionHandler)completionHandler;
open func calculateDistance(_ routePairs: [CSRoutePair], withCompletionHandler completionHandler: @escaping CSDirectionCompletionHandler)
You can request an UIImage of a desired map view with the following code snippet. You should create a CSMapSnapshotOptions beforehand to set custom properties.
CSMapSnapshotOptions *options = [[CSMapSnapshotOptions alloc] init];
options.center = [[CLLocation alloc] initWithLatitude:LATITUDE longitude:LONGITUDE];
options.zoomLevel = ZOOM_LEVEL;
options.size = CGSizeMake(WIDTH, HEIGHT);
[CSMapKit.sharedMapKit createMapSnapshotWithOptions:options withCompletionHandler:^(CSMapSnapshot * _Nullable snapshot, NSError * _Nullable error) {
}];
let options = CSMapSnapshotOptions()
options.center = CLLocation(latitude: LATITUDE, longitude: LONGITUDE)
options.zoomLevel = ZOOM_LEVEL
options.size = CGSize(width: WIDTH, height: HEIGHT)
CSMapKit.shared.createMapSnapshot(with: options) { (snapshot, error) in
}
Optionally, you can specify markeres to be drawn on the map by setting markers property on CSMapSnapshotOptions instance.
To run the example project, clone the repo, and run pod install from the Example directory first.
Then, in CSAppDelegate.m file, set your own clientID and clientSecret.
The example project is a mix of Swift and Objective-C.