TomTom SDK for iOS StructuredSearchSession

StructuredSearchSession

public protocol StructuredSearchSession

A session represents the current state of the structured search process. The search proceeds as a series of steps and intermediate searches until the client reaches the destination address.

  1. The session starts with the StructuredSearchSession.fetchStructuredSearchState(completion:) call, which returns the initial state.
  2. Then, the client can select a candidate in the current step with the ‘StructuredSearchSession.selectCandidate(candidate:completion:)call. [Optional] 3. After proceeding with the search, the client can go back to the previous step with theStructuredSearchSession.goBack(step:completion:)` call.

Here is a flow to get to the house address using Structured Search:

  • prefecture/metropolitan -> municipality -> oaza -> chome/aza -> (gaiku-)houseNumber(-sub)

For example:

  • “Japan” -> “Saitama Prefecture” -> “Saitama City Minami Ward” -> “Negishi” -> “5 chome” -> “2-13-3”

    Note

    for more information, see StructuredSearch documentation.

  • Fetch the current structured search state. This can be used to retrieve the initial state with candidates representing the top level of address, such as country.

    Note

    to proceed with the search, use the StructuredSearchSession.selectCandidate(candidate:completion:) call.

    Declaration

    Swift

    func fetchStructuredSearchState(completion: @escaping (Result<StructuredSearchResponse, Error>) -> ())

    Parameters

    completion

    The completion closure is called after the response to the request has been processed. If no errors occurred, StructuredSearchResponse contains the latest structured search state.
  • goBack(completion:) Extension method

    Go back to the previous selection from current step. If nothing was selected before, nothing will happen.

    Declaration

    Swift

    public func goBack(completion: @escaping (Result<StructuredSearchResponse, Error>) -> ())

    Parameters

    completion

    The completion closure is called after the response to the request has been processed. If no errors occurred, StructuredSearchResponse contains the latest structured search state.

  • Go back to previous selection from current step. step must be a positive value. If step is larger than the number of steps that have been taken, e.g. goBack is called with step set to 9 at the third step, it goes back to the first step.

    Declaration

    Swift

    func goBack(step: Int, completion: @escaping (Result<StructuredSearchResponse, Error>) -> ())

    Parameters

    step

    The number of step to go back.
    completion

    The completion closure is called after the response to the request has been processed. If no errors occurred, StructuredSearchResponse contains the latest structured search state.

  • Select a specific candidate in the current step. This will advance to the next step of the search path.

    Note

    to go back to the previous step, use the StructuredSearchSession.goBack(step:completion:) call.

    Declaration

    Swift

    func selectCandidate(
    candidate: StructuredSearchCandidate,
    completion: @escaping (Result<StructuredSearchResponse, Error>) -> ()
)

    Parameters

    candidate

    The candidate to select in the current step.
    completion

    The completion closure is called after the response to the request has been processed. If no errors occurred, StructuredSearchResponse contains the latest structured search state.

  • Set locale for the search session. The locale is used to find the best representation of strings in StructuredSearchCandidate.

    Declaration

    Swift

    func setLocale(locale: Locale, completion: @escaping (Result<StructuredSearchResponse, Error>) -> ())

    Parameters

    locale

    The preferred Locale.
    completion

    The completion closure is called after changing locale has been finished. If no errors occurred, StructuredSearchResponse contains the latest structured search state.