Places SDK - iOS

This iOS SDK is designed to be robust, user-friendly, and easy to integrate into any application. By providing powerful features like Autocomplete, Forward Geocoding, Reverse Geocoding, Place Details and NearbySearch, along with capabilities like configurable retry logic and automatic token refresh, this SDK is a comprehensive solution for place-related functionalities.

Designed to be lightweight, easy to integrate, this SDK ensures users have a seamless experience. It also includes periodic updates, making it highly reliable and user-friendly.

Purpose

The primary purpose of the Ola-Maps-Services SDK is to enable developers to seamlessly integrate the services including Autocomplete, Forward Geocoding, Reverse Geocoding, Place Details and NearbySearch.

Specifications

Before proceeding, ensure that you meet the following prerequisites:
  • Minimum iOS version: iOS 12.0.
  • Xcode Version: 12 or later.

Sample App

Please refer to theGithub Sample Appfor getting better clarity on same.

Installation

You have to download Places SDK import all the xcframeworks in your iOS project. Make sure you embed all the frameworks in General > Frameworks, Libraries and Embedded Content.

Features

  1. Autocomplete
  2. Forward Geocoding
  3. Reverse Geocoding
  4. Place Details
  5. NearbySearch
  6. TextSearch

Setup

First, you need to import OlaMapService in your project, and then initialize PlacesService. Initialize the SDK with API_KEY and the BASE_URL provided in the Platform dasboard.
let placesService = PlacesService(authKey: API_KEY, baseURL: BASE_URL)

Autocomplete

An Autocomplete API provides real-time suggestions to users as they type in a search bar or input field. It enhances user experience by predicting possible completions based on partial input, leveraging databases or external data sources. This API is essential for search engines, e-commerce sites, and data-entry applications.

/// Autocomplete search API
/// - Parameters:
///   - query: Search any place
///   - location: Provide the current location
///   - onCompletion: <AutoCompleteResponseModel, OlaServiceError>
func autocomplete(query: String, location: CLLocationCoordinate2D?) {
    placesService.autoCompleteResults(query: query, location: location) { result in
        switch result {
        case .success(let success):
            print("sucess = \(success)")
        case .failure(let failure):
            print("failure = \(failure.message)")
        }
    }
}

Forward Geocode

A Forward Geocoding API converts human-readable addresses into geographic coordinates (latitude and longitude). This API is vital for mapping services, location-based applications, and logistics, enabling users to input an address and receive precise location data for navigation, spatial analysis, and geolocation services.

/// Forward geocode
/// - Parameters:
///   - address: Enter the address you want to search
///   - language: Select the language you want. Default is english
///   - onCompletion: Result<ForwardGeocodeResponseModel, OlaServiceError>)
func forwardGeocode(address: String) {
    placesService.forwardGeocode(address: address) { result in
        switch result {
        case .success(let success):
            print("sucess = \(success)")
        case .failure(let failure):
            print("failure = \(failure.message)")
        }
    }
}

Reverse Geocoding

A Reverse Geocoding API transforms geographic coordinates (latitude and longitude) into human-readable addresses. This API is crucial for mapping applications, location-based services, and navigation systems, allowing users to obtain address details from a specific location point, facilitating user-friendly interfaces and enhanced location tracking.

/// Reverse Geocoding
/// - Parameters:
///   - latlng: Provide the location latitude and longitude with comma(,)separated formated.
///       - Ex: let latlng = "(Latitude),(Longitude)"
///   - onCompletion: <ReverseGeocodeResponseModel, OlaServiceError>
func reverseGeocode(latlng: String) {
  placesService.reverseGeocoding(latlng: latlng) { result in
    switch result {
        case .success(let success):
            print("sucess = \(success)")
        case .failure(let failure):
            print("failure = \(failure.message)")
    }
  }
}

Place Details

A Place Details API provides comprehensive information about a specific location, such as its name, address, contact details, opening hours, and user reviews. This API is essential for travel apps, local directories, and location-based services, enhancing user experience by offering detailed data on places of interest.

/// Get place details
/// - Parameters:
///   - placeId: provide the place id. You will get place_id from the autocomple search API or NearbySearch API response.
///   - onCompletion: <PlaceDetailsResponseModel, OlaServiceError>
func placeDetails(placeId: String) {
    placesService.getPlaceDetails(placeId: placeId) { result in
        switch result {
        case .success(let success):
            print("success = \(success)")
        case .failure(let failure):
            print("failure = \(failure.message)")
        }
    }
}
Place Icon

You can request URLs for PNG format icons, which indicate different types of places like coffee shops, restaurants, and hotels. The Place Details requests also provide the corresponding icon background colors.

  • iconMaskBaseURI
  • iconBackgroundColor
    • /// Setup place icon
let iconImageView = UIImageView()
let iconBackgroundView = UIView()
iconBackgroundView.addSubview(iconImageView)
var placeDetailsModel: PlaceDetailsResponseModel?

func setupIcon() {
  if let urlString = placeDetailsModel.result?.iconMaskBaseURI, let url = URL(string: urlString) {
      DispatchQueue.global().async {  
            guard let imageData = try? Data(contentsOf: url) else {
            print("Could not get image")
            return
          }
          
          DispatchQueue.main.async {
              iconImageView.image = UIImage(data: imageData)
          }
      }
  }
  
  if let backgroundColor = placeDetailsModel.result?.iconBackgroundColor, !backgroundColor.isEmpty {
      iconImageView.backgroundColor = UIColor(hexString: backgroundColor)
      iconBackgroundView.backgroundColor = UIColor(hexString: backgroundColor)
  }
}

    A Nearby Search API allows users to find points of interest within a specified radius from a given location. This API is essential for travel apps, local business directories, and location-based services, helping users discover nearby restaurants, shops, landmarks, and other amenities based on their current or specified location.

    /// NearBy search
/// - Parameters:
///   - types: Available category types:
///          • restaurant
///          • parking
///          • gas_station
///          • lodging
///          • bank
///          • hospital
///   - location: Provide the current location coordintes
///   - onCompletion: <AutoCompleteResponseModel, OlaServiceError>
func nearbyPlaces(categoryName: String, locationCoordinate: CLLocationCoordinate2D) {  
    placesService.getNearbySearch(categoryName, locationCoordinate: locationCoordinate) { result in
        switch result {
        case .success(let success):
            print("success = \(success)")
        case .failure(let failure):
            print("failure = \(failure.message)")
        }
    }
}

    TextSearch

    The Places Text Search returns a list of places based on an input query. For eg: "Cafes in Koramangala" or "Restaurant near Bangalore" or "Ola Electric". This is a web service that responds with a list of Places.

    /// Text Search API
/// - Parameters:
///   - input: Search for the popular places
///      - Example: Cafes in Koramangala, Cinemas in Koramangala etc...
///   - location: Optionally, you can specify a location to search around that particular location.
///   - onCompletion: Result<TextSearchResponseModel, OlaServiceError>
func textSearchAPI(input: String, location: CLLocationCoordinate2D?) {
    placesService.getTextSearch(input: input, location: location, onCompletion: { result in
        switch result {
        case .success(let success):
            print("success = \(success)")
        case .failure(let failure):
            print("failure = \(failure.message)")
        }
    })
}