12 Nov 2018

Geo Search

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 (IPv4 only)
  • 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 accommodate 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 is 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 are a good mix of nearby and 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.

We currently only support IPv4 addresses. If the user has an IPv6 address, aroundLatLngViaIP won’t work as intended.

Attributes returned within the results:


  • 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}

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.

  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.

  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.


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,

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


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,

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

Getting geo-search info with _rankingInfo

When you have several geo-locations in a record, you can know which geo-location has matched by asking the ranking information (getRankingInfo=true query parameter). You will have an attribute _rankingInfo on each of your records with relevance information, including the geo-location that matched when you are performing a geo-query. By using this information, you will be able to identify the geo-location that was used and to retrieve some associated information like the name.

Here is an example of _rankingInfo attribute returned on a record with several geo-location (the matchedGeoLocation attribute will be in _rankingInfo only if a geo-query is performed):

"_rankingInfo": {
    "nbTypos": 0,
    "firstMatchedWord": 0,
    "proximityDistance": 0,
    "userScore": 7,
    "geoDistance": 1600,
    "geoPrecision": 1,
    "nbExactWords": 0,
    "words": 0,
    "filters": 0,
    "matchedGeoLocation": {
        "lat": 37.3688,
        "lng": -122.036,
        "distance": 1600

Known issue with some geographical locations

If you allow users to filter areas all around the world, you may run into an issue where the selected area doesn’t match the result you get. That’s because the API assumes that the lowest longitude you give is the most westerly. While this applies to most of the world, this is no longer true as soon as you go across the 180th meridian because your most easterly longitude becomes a negative number.

The recommended workaround is to use the union of two adjacent rectangles around the meridian. For example, instead of setting insideBoundingBox to [70, 170, 60, -170], you would pass [[70, 170, 60, 180], [70, -180, 60, -170]].

This method also applies to insidePolygon, where you will likewise need to separate the polygon area into 2 series of coordinates:

  • series 1 will contain the area to the east of the meridian
  • series 2 will contain the remaining area, west of the meridian.

In other words, whenever your border crosses the meridian, you will need to choose which of the 2 series to place the resulting area.

Try these tutorials

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

© Algolia - Privacy Policy