Icon searching white

Geo Search

Last updated 10 August 2017

Geo Search overview

Geo Search is a way to filter and sort results by distance or around certain geo-locations.

Results can be retrieved through:

  • Filter and sort around a set of latitude and longitude coordinates
  • Filter and sort around the user’s location based on his/her IP address
  • Filter by one or more bounding boxes
  • Filter by one or more polygons

Before developing a Geo Search experience, you can check out the Algolia Places as it is used to support the frontend development for geo search.

Live demo

We built a demo showcasing geo search on a search for airports.

Adding Geo Info to Records

To enable the geo search feature, geodata is required in the records. The geolocation data is defined as a _geoloc object and it has to contain the lat and lng properties. The coordinates must be numbers, not strings.

Example of a record with one geolocation:

"_geoloc": {
  "lat": 40.639751,
  "lng:": -73.778925
}

Example of a record with multiple geolocations:

"_geoloc": [
  { "lat": 47.279430, "lng": 5.106450 },
  { "lat": 47.293228, "lng": 5.004570 },
  { "lat": 47.316669, "lng": 5.016670 }
]

Ranking Formula

The ranking formula contains a Geo criterion which by default is the second ranking criteria in the formula. This criterion is only effective when records contain the _geoloc attribute with the corresponding lat and lng properties. Results will be ranked by distance, from the closest to the farthest based on a point of reference.

The geo distance used for ranking is the distance between geo location in the search query and best matching geo location in the record, divided by geo precision (in meters).

The search query parameter aroundPrecision can be set to adjust the precision of the geo ranking. For example, with aroundPrecision=100, 2 results up to 100 meters distance will be considered as equal.

Around Precision

The search query parameter aroundPrecision is used to group results that could be ranked equally. This is often used to accomodate situations where other custom metrics are more important than just geo sorting.

By default, precision is measured in meters. When precision is set, the geo distance will be calculated by:

  • precision used when computed geo distance in meters (all distances will be floored to a multiple of this precision)

This parameter defines the precision of the sorting: results are sorted by ranges of distance whose size is equal to aroundPrecision.

If you set aroundPrecision to 200, you’ll have the following search results:

  • Group of results in the 0-200 meters range will be the best ranked (ranked equally)
  • Group of results in the 200-400 meters range will be ranked a bit lower
  • Group of results in the 400-600 meters range will be ranked even lower

For example when a user is looking for recommended restaurants around the area. The goal is to display results that is a good mix of a closeby and a highly rated restaurants.

Given that, there are 2 restaurants within 200 meters from the user’s location:

  • restaurant A with a 5 star rating and distance of 150 meters (farther)
  • restaurant B with a 3 star rating and distance of 100 meters (closer)

If we are only sorting by geo distance, restaurant B will be ranked higher since it is closer to the user.

But by setting aroundPrecision to 200, restaurant A and B will be ranked equally. Since the results are tied under the Geo criterion, the search engine will examine the other criteria in the ranking formula to further sort the results. Restaurant A will be ranked higher in the result due to its higher rating.

Sorting by Distance from a point

When searching around a location, the results can be sorted by distance - the closer the record is to the lat/lng you provided, the higher it is in the results.

To search for results near a location, you can set a search query parameter aroundLatLng to a lat and lng coordinate, which will be used as a point of reference. Algolia will then expand the search from this point and the results will be sorted based on the distance from that specific location.

To search for results near the user’s location, you can set a search query parameter aroundLatLngViaIP to true. So the results will be sorted based on the distance from the user’s location.

Automatic Radius

By default, Algolia will expand the search radius around the specified latitude and longitude until approximatively 1000 hits are found. If the area is dense, the radius will be smaller. If it’s not dense, the radius will be bigger.

The benefit of this feature is that it increases the chance of finding more results in low density areas. If a fixed radius is set, there could be less/no results returned.

The automaticRadius field only gets returned in the search response for geo queries without an explicitly specified radius.

Around Radius

A fixed radius can be set in order for Algolia to return results only within the specified radius.


index.search({
  query: 'query',
  aroundRadius: 1000 // 1km Radius
}).then(res => {
  // console.log(res);
});

Minimum Around Radius

When using the automatic radius feature, a minimum radius can be set to ensure that the search will at least cover the area around the specified radius.


index.search({
  query: 'query',
  minimumAroundRadius: 1000 // 1km Radius
}).then(res => {
  // console.log(res);
});

Filtering inside an area

Results can be restricted to a given area by setting bounding shapes (eg. rectangle, polygon) in the search parameters. All results outside of the shape(s) will be excluded from the results.

To restrict results within a given area, you should include the lat and lng of a bounding shape in the search parameters. All results outside of the shape will be excluded from the results.

The feature “Filter inside an area” only filters the records and doesn’t have any impact on the ranking of results. However, it cannot be used along with aroundLatLng and aroundLatLngViaIP parameters. Those parameters will be ignored when using a bounding box.

Rectangle

The search query parameter insideBoundingBox filters the results inside the area defined by the two opposite points of a rectangle.


const boundingBox = [
  // P1 lat, lng
  46.650828100116044, 7.123046875,
  // P2 lat, lng
  45.17210966999772, 1.009765625,
];

index.search({
  query: 'query',
  insideBoundingBox: [boundingBox]
}).then(res => {
  // console.log(res);
});

Polygon

The search query parameter insidePolygon filters the results inside the area defined by the points of a custom shape.


const polygon = [
  // P1 lat, lng
  46.650828100116044, 7.123046875,
  // P2 lat, lng
  45.17210966999772, 1.009765625,
  // P3 lat, lng
  49.62625916704081, 4.6181640625,
];

index.search({
  query: 'query',
  insidePolygon: [polygon]
}).then(res => {
  // console.log(res);
});

Sorting by Distance to a point

To search for results near a location, you can set a search query parameter aroundLatLng to a lat and lng coordinate, which will be used as a point of reference and Algolia will then expand the search from this point. The results will be sorted based on the distance from the specified location.

To search for results near the user’s location, you can set aroundLatLngViaIP to true. Algolia will associate a location based on the user’s IP address and search around that location. The results will be sorted based on the distance from the user’s location.

Attributes returned within the results:

matchedGeoLocation:

  • geo location that matched the query
  • lat (float): latitude of matched location
  • lng (float): longitude of matched location
  • distance (integer): distance between the matched location and the search location (in meters) Caution: contrary to geoDistance, this value is not divided by the geo precision

aroundLatLng (string, optional):

  • only returned when aroundLatLngViaIP is set
  • computed geo location
  • legacy reason (param is string not object) –> ${lat}, ${lng}

What’s Next

Continue building your Algolia knowledge with these concepts:

If you want to get started using Algolia’s geo-features, we have a few tutorials you might find helpful:

© Algolia - Privacy Policy