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.
- The session starts with the
StructuredSearchSession.fetchStructuredSearchState(completion:)
call, which returns the initial state. - 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 the
StructuredSearchSession.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, seeStructuredSearch
documentation.Important
This is a Public Preview API. It may be changed or removed at any time.
-
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 theStructuredSearchSession.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. -
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 theStructuredSearchSession.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. -
Go back to previous selection from current step.
step
must be a positive value. Ifstep
is larger than the number of steps that have been taken, e.g.goBack
is called withstep
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. -
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.