Configure the Woosmap MultiSearch

Explore available parameters and understand how to combine the different autocomplete services

  1. How to set API configuration up
  2. Fallback configuration
  3. How to set the autocomplete configuration
  4. Get location details from suggestion id

How to set API configuration up

The library requires to set a key for each available API in your MultiSearch implementation, whether it’s a Woosmap API or for Google Places API.

Please refer to the documentation to get an API Key if necessary.

const multisearch = woosmap.multisearch({
  store: {
    key: "woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" // your woosmap project public key
  },
  localities: {
    key: "woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" // your woosmap project public key
  },
  address: {
    key: "woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" // your woosmap project public key
  },
  places: {
    key: "{your_google_api_key}"
  }
});

API options

Additionally, for each API configuration you can apply the same optional parameters as defined in the concerned REST API’s documentation.

Documentation:

Set the optional params field

const multisearch = woosmap.multisearch({
  localities: {
    key: "woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // your woosmap project public key
    params: {
      components: { country: ["FR", "GB"]},
      language: "en",
      types: ["locality", "country", "postal_code"]
    }
  },
  address: {
    key: "woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // your woosmap project public key
    params: {
      components: { country: ["FR", "GBR"] },
      language: "en",
    }
  },
  store: {
    key: "woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // your woosmap project public key
    params: {
      query: 'type:"bose_store"'
    }
  },
  places: {
    key: "{your_google_api_key}",
    params: {
      components: { country: ["FR", "GB"] }
    }
  }
});

Fallback configuration

When we created this Library, we decided to implement a fallback system enabling to switch from one API to another. This system is flexible and can be manually adjusted for each API in order to be efficient for each of your specific use cases.

Two parameters have an impact on the fallback:

minInputLength

Autocomplete service will return an empty result and no fallback will be triggered until the input length reaches the minInputLength value.

fallbackBreakpoint

Two possible uses for the fallbackBreakpoint parameter:

A default value is defined for each API:

API parameter name default fallbackBreakpoint
Woosmap Search API (stores) store 1
Woosmap Localities API localities 0.4
Woosmap Address API address 0.5
Google Places API places 1

How is the score calculated?

The score could be considered as a Levenshtein Distance between those two strings: the input from the user and the value (formatted_address or store_name) of a returned autocomplete item. We use the fuzzy searching JavaScript library Fuse.js.

Generally speaking, fuzzy searching (formerly known as approximate string matching) is the technique of finding strings that are approximately equal to a given pattern (rather than exactly).

Have a look at the Fuse.js scoring explanation for more details.

Example

const multisearch = woosmap.multisearch({
  store: {
    key: "woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // your woosmap project public key
    fallbackBreakpoint: false,
    minInputLength: 2
  },
  localities: {
    key: "woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // your woosmap project public key
    fallbackBreakpoint: 0.3,
    minInputLength: 2
  },
  address: {
    key: "woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // your woosmap project public key
    fallbackBreakpoint: 1,
    minInputLength: 4
  },
  places: {
    key: "{your_google_api_key}",
    fallbackBreakpoint: 1,
    minInputLength: 6
  }
});

How to set the autocomplete configuration

Once you have configured your APis and the fallback logics, you can start using the autocompleteMulti() service. You now have to define the order in which the APIs will be called by setting the apiOrder field. Find a full example in the Sample page.

Get location details from suggestion id

The MultiSearch Library also provides a detailsMulti() service. It returns a JSON/Object response containing all location data based on a location Id previously retrieved in the Location autocomplete suggestion.

Its response contains all the pieces of information you may need to standardize in order to improve the user experience, to get accurate location of a location, to split an address in components for further use cases, and so on.

detailMulti() response definition

The detailsMulti() service response consists of a common part made of 5 fields:

A specific part contains all data returned by the requested API. The field items encapsulates this data.

Example

{
   "formatted_address":"Via del Corso, 186, 00187 Roma RM, Italia",
   "geometry":{
      "location_type":"ROOFTOP",
      "location":{
         "lat":41.90207,
         "lng":12.4801
      },
      "viewport":{
         "northeast":{
            "lat":41.90297,
            "lng":12.48131
         },
         "southwest":{
            "lat":41.90117,
            "lng":12.47889
         }
      }
   },
   "id":"dW5kZWZpbmVk",
   "types":[
      "house_number"
   ],
   "name":"",
   "address_components":[
      {
         "types":[
            "country"
         ],
         "long_name":"Italia",
         "short_name":"IT"
      },
      {
         "long_name":"Roma",
         "short_name":"Roma",
         "types":[
            "locality"
         ]
      },
      {
         "long_name":"Via del Corso",
         "short_name":"Via del Corso",
         "types":[
            "route"
         ]
      },
      {
         "long_name":"00187",
         "short_name":"00187",
         "types":[
            "postal_code"
         ]
      },
      {
         "long_name":"186",
         "short_name":"186",
         "types":[
            "street_number"
         ]
      }
   ],
   "item":{
      "address_components":[
         {
            "types":[
               "country"
            ],
            "long_name":"Italia",
            "short_name":"IT"
         },
         {
            "types":[
               "state"
            ],
            "long_name":"Lazio",
            "short_name":"Lazio"
         },
         {
            "types":[
               "county"
            ],
            "long_name":"Roma",
            "short_name":"RM"
         },
         {
            "long_name":"Roma",
            "short_name":"Roma",
            "types":[
               "locality"
            ]
         },
         {
            "long_name":"Colonna",
            "short_name":"Colonna",
            "types":[
               "district"
            ]
         },
         {
            "long_name":"Via del Corso",
            "short_name":"Via del Corso",
            "types":[
               "route"
            ]
         },
         {
            "long_name":"00187",
            "short_name":"00187",
            "types":[
               "postal_code"
            ]
         },
         {
            "long_name":"186",
            "short_name":"186",
            "types":[
               "street_number"
            ]
         }
      ],
      "formatted_address":"Via del Corso, 186, 00187 Roma RM, Italia",
      "geometry":{
         "location_type":"ROOFTOP",
         "location":{
            "lat":41.90207,
            "lng":12.4801
         },
         "viewport":{
            "northeast":{
               "lat":41.90297,
               "lng":12.48131
            },
            "southwest":{
               "lat":41.90117,
               "lng":12.47889
            }
         }
      },
      "types":[
         "house_number"
      ]
   }
}
Was this article helpful?
Have more questions? Submit a request