Geo Search with InstantSearch.js

Overview

We will see how we can leverage the geo search capabilities of Algolia with the geoSearch widget. The widget is implemented on top of Google Maps but the core logic is not tied to any map provider. You can build your own map widget with the connectGeoSearch connector and a different provider (e.g. Leaflet).

Before diving into the usage keep in mind that you are responsible for loading the Google Maps library. You can find more information about that in the Google Maps documentation.

Dataset

We’ll use a dataset of 3000+ records of the biggest airports in the world.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
 {
    "objectID": "3797",
    "name": "John F Kennedy Intl",
    "city": "New York",
    "country": "United States",
    "iata_code": "JFK",
    "links_count": 911
    "_geoloc": {
      "lat": 40.639751,
      "lng": -73.778925
    },
  }
]

To be able to display hits on the map, we have the latitude and longitude stored in the record. We recommend storing it in the _geoloc attribute as it will allow you to do geo-filtering and and geo-sorting.

You can download the dataset on GitHub. Have a look at how to import it in Algolia.

Configure Index Settings

When displaying on a map, you still want the relevance to be good. For that let’s configure the index.

• searchable attributes: we’re going to search in our 4 textual attributes: name, city, country and iata_code.
• custom ranking: let’s use the number of other connected airports links_count as a ranking metric. The more connections the better.

1
2
3
4
$index->setSettings([
  'searchableAttributes' => ['name', 'city', 'country', 'iata_code'],
  'customRanking' => ['desc(links_count)']
]);

1
2
3
4
index.set_settings(
  searchableAttributes: ['name', 'city', 'country', 'iata_code'],
  customRanking: ['desc(links_count)']
)

1
2
3
4
5
6
index.setSettings({
  searchableAttributes: ['name', 'city', 'country', 'iata_code'],
  customRanking: ['desc(links_count)'],
}).then(() => {
  // done
});

1
2
3
4
index.set_settings({
    "searchableAttributes": ["name", "city", "country", "iata_code"],
    "customRanking": ["desc(links_count)"]
})

1
2
3
4
5
6
7
8
9
index.setSettings(
  settings: [
    "searchableAttributes": ["name", "city", "country", "iata_code"],
    "customRanking": ["desc(links_count)"]
  ],
  completionHandler: { (content, error) -> Void in
    // [...]
  }
)

1
2
3
4
5
6
7
8
9
10
11
12
13
IndexSettings settings = new IndexSettings
{
  SearchableAttributes = new List<string> 
  {
    "name",
    "city",
    "country",
    "iata_code"
  },
  CustomRanking = new List<string> {"desc(links_count)"}
};

index.SetSettings(settings);

1
2
3
4
5
6
7
8
9
10
index.setSettings(
  new IndexSettings()
    .setSearchableAttributes(Arrays.asList(
      "name",
      "city",
      "country",
      "iata_code"
    ))
    .setCustomRanking(Arrays.asList("desc(links_count)"))
);

1
2
3
4
index.SetSettings(search.Settings{
  "searchableAttributes": []string{"name", "city", "country", "iata_code"},
  "customRanking": []string{"desc(links_count)"},
})

1
2
3
4
5
6
7
8
9
10
11
12
13
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    searchableAttributes = Some(Seq(
      SearchableAttributes.attribute("name"),
      SearchableAttributes.attribute("city"),
      SearchableAttributes.attribute("country"),
      SearchableAttributes.attribute("iata_code")
    )),
    customRanking = Some(Seq(
      CustomRanking.desc("links_count")
    ))
  )
}

Hits on the map

This is the most simple use case for the geoSearch widget. It displays your results on a Google Maps. Note that in the example we explicitly set the height of the parent container. This is a requirement of Google Maps; don’t forget to set it, otherwise the map won’t be displayed.

The widget will set the zoom and position of the map according to the hits retrieved by the search. In case the search doesn’t return any results the map will fall back to its initialZoom and initialPosition . By default, once you move the map the widget will use the bounding box of the map to filter the results. You can find all the available options of the widget in the documentation.

Since the widget is built on top of Google Maps you might want to apply some options to your maps. For example you might want to switch on a satellite image rather than a normal street map. You can provide those extra options to the mapOptions attribute of the geoSearch widget and they will be forwarded to the Google Maps instance.

All examples in this guide assume you’re including InstantSearch.js in your web page via a CDN. If you’re using it with a package manager, you should adjust the way you import InstantSearch.js and its widgets. Read How to install InstantSearch.js for more information.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
const search = instantsearch({
  indexName: 'airports',
  searchClient,
});

search.addWidgets([
  instantsearch.widgets.searchBox({
    container: '#searchbox',
  }),

  instantsearch.widgets.geoSearch({
    container: '#maps',
    googleReference: window.google,
    mapOptions: {
      mapTypeId: window.google.maps.MapTypeId.SATELLITE,
    },
  })
]);

search.start();

You can find a live example on CodeSandbox. The source code is available on GitHub. More examples with the widget are available inside the widget showcase.

Custom Marker

The standard marker API of Google Maps let you update the image of the marker. Images are nice but what about adding information stored in your hits on the marker with a custom styling. To achieve this we provide an option customHTMLMarker. The widget accept a regular template like any other InstantSearch.js widgets.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
const search = instantsearch({
  indexName: 'airports',
  searchClient,
});

search.addWidgets([
  instantsearch.widgets.searchBox({
    container: '#searchbox',
  }),

  instantsearch.widgets.geoSearch({
    container: '#maps',
    googleReference: window.google,
    templates: {
      HTMLMarker: `
        <span class="marker">
          {{ city }} - {{ airport_id }}
        </span>
      `,
    },
  })
]);

search.start();

You can find a live example on CodeSandbox. The source code is available on GitHub. More examples with the widget are available inside the widget showcase.

Control

A common pattern that comes with a geo search experience is the ability to control how the refinement behaves from the map. By default the widget will use the map bounding box to filter the results as soon the map has moved. But sometimes it’s better for the experience to let the user choose when he wants to apply the refinement. This way he can explore the map without having the results changing every time. For this pattern we provide an option called enableRefineControl) that let the user control how the refinement behaves directly from the widget. You can also control the default value applied to the checkbox of the control component with enableRefineOnMapMove).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
const search = instantsearch({
  indexName: 'airports',
  searchClient,
});

search.addWidgets([
  instantsearch.widgets.searchBox({
    container: '#searchbox',
  }),

  instantsearch.widgets.geoSearch({
    container: '#maps',
    googleReference: window.google,
    enableRefineControl: true,
    enableRefineOnMapMove: false,
  })
]);

search.start();

You can find a live example on CodeSandbox. The source code is available on GitHub. More examples with the widget are available inside the widget showcase.