TravelKit

 
@interface TravelKit : NSObject

The main class currently used for authentication and data fetching. It provides a singleton instance with the public +sharedKit method which may be used to work with the Travel backend.

The basic workflow is pretty straightforward – to start using TravelKit, you only need a couple of lines to get the desired data.

// Get shared instance
TravelKit *kit = [TravelKit sharedKit];

// Set your API key
kit.APIKey = @"<YOUR_API_KEY_GOES_HERE>";

// Ask kit for Eiffel Tower TKPlace object with details
[kit detailedPlaceWithID:@"poi:530" completion:^(TKPlace *place, NSError *e) {
    if (place) NSLog(@"Let's visit %@!", place.name);
    else NSLog(@"Something went wrong :/");
}];

Warning

API key must be provided, otherwise using any methods listed below will result in an error being returned in a call completion block.

Key properties

  • Client API key you’ve obtained.

    Warning

    This needs to be set in order to perform data requests successfully.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *APIKey;

    Swift

    var apiKey: String? { get set }

  • Preferred language of response data to use.

    Note

    Supported language codes: en, fr, de, es, nl, pt, it, ru, cs, sk, pl, tr, zh, ko.

    Default language code is en.

    If you want to enforce specific language or pick the one depending on your own choice, simply set one of the options listed.

    Warning

    This needs to be set in order to receive translated content.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, null_resettable) NSString *language;

    Swift

    var language: String! { get set }

Initialisation

  • Shared singleton object to work with.

    Warning

    Regular -init and +new methods are not available.

    Declaration

    Objective-C

    + (nonnull TravelKit *)sharedKit;

    Swift

    class func shared() -> TravelKit

    Return Value

    Singleton TravelKit object.

Place working queries

  • Returns a collection of TKPlace objects for the given query object.

    This method is good for fetching Places to use for lists, map annotations and other batch uses.

    Declaration

    Objective-C

    - (void)placesForQuery:(nonnull TKPlacesQuery *)query
            completion:(nonnull void (^)(NSArray<TKPlace *> *_Nullable,
                                         NSError *_Nullable))completion;

    Swift

    func places(for query: TKPlacesQuery, completion: @escaping ([TKPlace]?, Error?) -> Void)

    Parameters

    query

    TKPlacesQuery object containing the desired attributes to look for.
    completion

    Completion block called on success or error.

  • Returns a collection of TKPlace objects for the given IDs.

    Declaration

    Objective-C

    - (void)placesWithIDs:(nonnull NSArray<NSString *> *)placeIDs
           completion:(nonnull void (^)(NSArray<TKPlace *> *_Nullable,
                                        NSError *_Nullable))completion;

    Swift

    func places(withIDs placeIDs: [String], completion: @escaping ([TKPlace]?, Error?) -> Void)

    Parameters

    placeIDs

    Array of strings matching desired Place IDs.
    completion

    Completion block called on success or error.

  • Returns a Detailed TKPlace object for the given global Place identifier.

    This method is good for fetching further Place information to use f.e. on Place Detail screen.

    Declaration

    Objective-C

    - (void)detailedPlaceWithID:(nonnull NSString *)placeID
                 completion:(nonnull void (^)(TKPlace *_Nullable,
                                              NSError *_Nullable))completion;

    Swift

    func detailedPlace(withID placeID: String, completion: @escaping (TKPlace?, Error?) -> Void)

    Parameters

    placeID

    Global identifier of the desired Place.
    completion

    Completion block called on success or error.

Media working queries

  • Returns a collection of TKMedium objects for the given global Place identifier.

    This method is used to fetch all Place media to be used f.e. for Gallery screen.

    Declaration

    Objective-C

    - (void)mediaForPlaceWithID:(nonnull NSString *)placeID
                 completion:(nonnull void (^)(NSArray<TKMedium *> *_Nullable,
                                              NSError *_Nullable))completion;

    Swift

    func mediaForPlace(withID placeID: String, completion: @escaping ([TKMedium]?, Error?) -> Void)

    Parameters

    placeID

    Global identifier of the desired Place.
    completion

    Completion block called on success or error.

Tours working queries

  • Returns a collection of TKTour objects for the given query object.

    This method is good for fetching Tours to use for lists and other batch uses.

    Note

    Experimental.

    Declaration

    Objective-C

    - (void)toursForQuery:(nonnull TKToursQuery *)query
           completion:(nonnull void (^)(NSArray<TKTour *> *_Nullable,
                                        NSError *_Nullable))completion;

    Swift

    func tours(for query: TKToursQuery, completion: @escaping ([TKTour]?, Error?) -> Void)

    Parameters

    query

    TKToursQuery object containing the desired attributes to look for.
    completion

    Completion block called on success or error.

Favorites

  • Fetches an array of IDs of Places previously marked as favorite.

    Declaration

    Objective-C

    - (nonnull NSArray<NSString *> *)favoritePlaceIDs;

    Swift

    func favoritePlaceIDs() -> [String]

    Return Value

    Array of Place IDs.

  • Updates a favorite state for a specific Place ID.

    Declaration

    Objective-C

    - (void)updateFavoritePlaceID:(nonnull NSString *)favoriteID
                  setFavorite:(BOOL)favorite;

    Swift

    func updateFavoritePlaceID(_ favoriteID: String, setFavorite favorite: Bool)

    Parameters

    favoriteID

    Place ID to update.
    favorite

    Desired Favorite state, either YES or NO.

Map-related methods

  • Naive method for fetching standardised quad keys for the given region.

    Declaration

    Objective-C

    - (nonnull NSArray<NSString *> *)quadKeysForMapRegion:
    (MKCoordinateRegion)region;

    Swift

    func quadKeys(forMapRegion region: MKCoordinateRegion) -> [String]

    Parameters

    region

    Region to calculate quad keys for.

    Return Value

    Array of quad key strings.

  • Spreading method calculating optimally spread TKMapPlaceAnnotation objects in 3 basic sizes.

    Declaration

    Objective-C

    - (nonnull NSArray<TKMapPlaceAnnotation *> *)
spreadAnnotationsForPlaces:(nonnull NSArray<TKPlace *> *)places
                 mapRegion:(MKCoordinateRegion)region
               mapViewSize:(CGSize)size;

    Swift

    func spreadAnnotations(for places: [TKPlace], mapRegion region: MKCoordinateRegion, mapViewSize size: CGSize) -> [TKMapPlaceAnnotation]

    Parameters

    places

    Places to spread and create TKMapPlaceAnnotation objects for.
    region

    Region where to spread the annotations.
    size

    Standard size of the Map view. May be taken from either -frame or -bounds.

    Return Value

    Array of spread annotations.

  • Interpolating method for sorting Map annotations.

    Note

    toAdd, toKeep and toRemove are regular given mutable arrays this method will fill. Annotations in toAdd array are meant to be used with -addAnnotations: or equivalent method of your Map view, toRemove accordingly with -removeAnnotations: method.

    Declaration

    Objective-C

    - (void)
interpolateNewAnnotations:
    (nonnull NSArray<TKMapPlaceAnnotation *> *)newAnnotations
           oldAnnotations:
               (nonnull NSArray<TKMapPlaceAnnotation *> *)oldAnnotations
                    toAdd:
                        (nonnull NSMutableArray<TKMapPlaceAnnotation *> *)toAdd
                   toKeep:
                       (nonnull NSMutableArray<TKMapPlaceAnnotation *> *)toKeep
                 toRemove:
                     (nonnull NSMutableArray<TKMapPlaceAnnotation *> *)toRemove;

    Swift

    func interpolateNewAnnotations(_ newAnnotations: [TKMapPlaceAnnotation], oldAnnotations: [TKMapPlaceAnnotation], toAdd: NSMutableArray, toKeep: NSMutableArray, toRemove: NSMutableArray)

    Parameters

    newAnnotations

    Array of annotations you’d like to display.
    oldAnnotations

    Array of annotations currently displayed.
    toAdd

    Out array of annotations to add to the map.
    toKeep

    Out array of annotations to keep on the map.
    toRemove

    Out array of annotations to remove from the map.

Session-related methods

  • Clears all cached and persisting user data.

    Declaration

    Objective-C

    - (void)clearUserData;

    Swift

    func clearUserData()