@woosmap/multisearch v1.0.6

Introduction

Multisearch makes querying geographical data easy by combining Woosmap Localities, Woosmap Address and Google Places Autocomplete APIs in a single lightweight and easy to use library.

• Supports callbacks and promises
• Compatible with IE11

Table of contents

• Installation
• Getting started
• Usage
• Options
• Examples

Installation

88KB all-in-one browser bundle (dependencies included):

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@woosmap/multisearch/dist/main.bundle.js"></script>

You can then instantiate the library with the global woosmap.multisearch() function.

Dependencies:

• Fuse.js

Getting started

const {
	autocompleteLocalities,
	autocompleteAddress,
	search,
	geocodeLatlng,
	geocodeAddress,
} = woosmap.multisearch({
  localities: {
    apiKey: 'YOUR_WOOSMAP_API_KEY',
    options: { ... },
  },
  address: {
    apiKey: 'YOUR_WOOSMAP_API_KEY',
    options: { ... },
  },
  places: {
    apiKey: 'YOUR_GOOGLE_API_KEY',
    options: { ... },
  },
});
const query = {
  input: '12 rue de Paris',
  apiOrder: ['localities', 'address', 'places'],
  options: {
    localities: { ... },
    address: { ... },
    places: { ... },
  },
};

// Using Promises
search(query).then((results) => console.log(results), (error) => {});
// Using Callbacks
search(query, (error, results) => console.log(results));

Usage

autocompleteLocalities

Search querying Woosmap Localities autocomplete. You can pass through Localities Autocomplete API options with the optionals key within the query object.

woosmap.autocompleteLocalities({ input, optionals }, callback)

• query Object: Your query parameters input: String, optionals: Object
• callback Function: Optional function(error, results)

{
  "status": 200,
  "body": [
    {
      "public_id": "fzeHfrgd2PzHDM3Beq46U2/zE0o=",
      "description": "Paris, France",
      "name": "Paris",
      "type": "locality",
      "location": {
        "lat": 48.856697,
        "lng": 2.3514616
      },
      "matched_substrings": {
        "name": [
          {
            "offset": 0,
            "length": 5
          }
        ],
        "admin_1": [
          {
            "offset": 0,
            "length": 5
          }
        ],
        "description": [
          {
            "offset": 0,
            "length": 5
          }
        ]
      },
      "viewpoint": {
        "bounds": {
          "east": 2.469769,
          "south": 48.815605,
          "north": 48.90201,
          "west": 2.224225
        }
      },
      "admin_1": "Paris",
      "postal_codes": [
        "75001",
        "75002",
        "75003",
        "75004",
        "75005",
        "75006",
        "75007",
        "75008",
        "75009",
        "75010",
        "75011",
        "75012",
        "75013",
        "75014",
        "75015",
        "75016",
        "75017",
        "75018",
        "75019",
        "75020",
        "75116"
      ],
      "locality": "",
      "admin_0": "France"
    }
  ]
}

autocompleteAddress

Search querying Woosmap Address autocomplete. You can pass through Address Autocomplete API options with the optionals key within the query object.

autocompleteAddress({ input, optionals }, callback)

• query Object: Your query parameters input: String, optionals: Object
• callback Function: Optional function(error, results)

 {
   "status": 200,
   "body": [
     {
       "description": "Rue de l'Ouest, 44100 Nantes, France",
       "matched_substring": {
         "description": [
           {
             "offset": 0,
             "length": 14
           }
         ]
       },
       "type": "street_address"
     }
   ]
 }

geocodeLatlng

Search querying Woosmap Address geocode. You can pass through Address Geocode API options with the optionals key within the query object.

geocodeLatlng({ input, optionals }, callback)

• query Object: Your query parameters input: String, optionals: Object
• callback Function: Optional function(error, results)

 {
   "status": 200,
   "body": [
     {
       "address_components": [
         [
           "Stat. de la Liberté, New York, NY 10004, États-Unis",
           "NY",
           "New York",
           "New York",
           "Liberty Island",
           "New York"
         ],
         {
           "types": [
             "country"
           ],
           "short_name": "USA",
           "long_name": "États-Unis"
         },
         {
           "long_name": "New York",
           "short_name": "New York",
           "types": [
             "locality"
           ]
         },
         {
           "long_name": "10004",
           "short_name": "10004",
           "types": [
             "postal_code"
           ]
         }
       ],
       "formatted_address": "Stat. de la Liberté, New York, NY 10004, États-Unis",
       "geometry": {
         "location_type": "APPROXIMATE",
         "location": {
           "lat": 40.68925,
           "lng": -74.04445
         }
       },
       "types": [
         "place",
         "sights_and_museums",
         "leisure_and_outdoor"
       ]
     }
   ]
 }

geocodeAddress

Search querying Woosmap Address geocode. You can pass through Address Geocode API options with the optionals key within the query object.

geocodeAddress({ input, optionals }, callback)

• query Object: Your query parameters input: String, optionals: Object
• callback Function: Optional function(error, results)

 {
   "status": 200,
   "body": [
     {
       "description": "12 Rue de Paris, 94190 Villeneuve-Saint-Georges, France",
       "matched_substring": {
         "description": [
           {
             "offset": 0,
             "length": 2
           },
           {
             "offset": 3,
             "length": 12
           }
         ]
       },
       "type": "street_number"
     }
   ]
 }

search

Search querying Woosmap Localities, Woosmap Address and Google Places Autocomplete APIs.

search({ input, apiOrder, options }, callback)

• query Object: Your query parameters input: String, apiOrder: Array, options: Object
• callback Function: Optional function(error, results)

 {
   "status": 200,
   "body": [
     {
       "description": "12 Rue Desnouettes, 75015 Paris, France",
       "matched_substring": {
         "description": [
           {
             "offset": 0,
             "length": 2
           },
           {
             "offset": 3,
             "length": 6
           }
         ]
       },
       "type": "street_number"
     }
   ]
 }

Options

Global options

You can globally customize the behavior of the differents APIs, each service has a corresponding key where you can specify its behavior with the options object.

You must define a breakpoint value from 0 to 1 on each service, which sets the threshold where the service's results will be discarded and another call to the fallback service will be made. A value of 0 indicates that the results must contain at least one perfect match while 1 will match anything.

Availables options:

• localities: Woosmap Localities Autocomplete API options
• address: Woosmap Address Autocomplete API options
• search: Search Options
• google: Google Places Autocomplete

Per call options overwrite global options.

const multisearch = woosmap.multisearch({
  localities: {
    apiKey: 'YOUR_WOOSMAP_API_KEY',
    breakpoint: 0.5,
    options: {
      types: ['country', 'postal_code'],
    },
  },
  address: {
    apiKey: 'YOUR_WOOSMAP_API_KEY',
    breakpoint: 0.7,
    options: {
      components: {
        country: ['FRA', 'ITA'],
        language: 'fr',
      },
    },
  },
  places: {
    apiKey: 'YOUR_GOOGLE_API_KEY',
    breakpoint: 0.8,
    options: {
      components: {
        country: ['us', 'pr'],
      },
    },
  },
});

Woosmap Address and Woosmap Localities options

You can customize the calls to Woosmap Localities and Woosmap Address on a per call basis with the optionals key within the query object.

Woosmap Localities Autocomplete

You can pass through Localities API options

const results = await autocompleteLocalities({
  input: 'Paris',
  optionals: {
    types: ['locality', 'airport', 'admin_level'],
    components: {
      country: ['gb', 'fr', 'be', 'sp', 'it'],
    },
    language: 'fr',
    data: 'advanced',
    extended: 'postal_code',
  },
});

Woosmap Address Autocomplete

You can pass through Address Autocomplete API options.

const results = await autocompleteAddress({
  input: '12 rue de Paris',
  optionals: {
    components: {
      country: ['CAN', 'BEL'],
    },
    language: 'fr',
  },
});

Woosmap Address Geocode

You can pass through Address Geocode API options.

const results = await geocodeAddress({
  input: '12 rue de Paris',
  optionals: {
    components: {
      country: ['CAN', 'BEL'],
    },
    language: 'fr',
  },
});

const results = await geocodeLatlng({
  input: '40.689247,-74.044502',
  optionals: {
    components: {
      country: ['CAN', 'BEL'],
    },
    language: 'fr',
  },
});

Search options

You must set the order in which the differents APIs will be called on a per call basis with the apiOrder option. The APIs will be called from left to right.

You can also customize the differents APIs with the options key.

Per call options overwrite global options

const results = await search({
  input: '12 rue de Paris',
  apiOrder: ['localities', 'address', 'places'],
  options: {
    localities: { ... },
    address: { ... },
    places: { ... },
  },
});

Examples

Demo fiddle

Tests

Test files are located within the src/tests folder.

To run the tests suite, run yarn test.