Geo Location

Geo Search

Geo Search is a way to filter and sort results by distance or around certain geographical locations. You can limit your results to a street, to a city or cities, to one or more parts of the world. You can sort your results according to how near or far they are to a certain defined geolocation.

Geo offers you various possibilities:

• 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 box-shaped geographical areas (bounded boxes)
• Filter by one or more freely-drawn geographical areas (polygons)

Enabling Geo Search by Adding Geo Info to Records

To enable the geo search feature, geolocation data is required in your records. Geodata is defined as a _geoloc object, which contains the lat and lng properties. The coordinates must be numbers, not strings.

Example of a record with one geolocation:

1
2
3
4
"_geoloc": {
  "lat": 40.639751,
  "lng": -73.778925
}

Example of a record with multiple geo locations:

1
2
3
4
5
"_geoloc": [
  { "lat": 47.279430, "lng": 5.106450 },
  { "lat": 47.293228, "lng": 5.004570 },
  { "lat": 47.316669, "lng": 5.016670 }
]

Once your records contain geo information you can do two things:

1. Geographical Filtering
2. Geographical Ranking

Geographical Filtering

Geo search filters results based on a set of geographic coordinates: Only records that fall within a specified set of geolocations will be returned. You can define one or more geographic areas, and send back all records that match the query and fall within the geo-coordinates that you’ve defined.

This is the default behavior. In a later section on this page, you will find ways to refine this behavior by changing boundaries, distance, or precision.

Filter around a central point

You can define a central geographical point and show only records that fall within a certain radius of that point. This central point is defined in one of two ways:

• either it is sent along with the query
• or it is derived using the user’s IP address (supports only IPv4)

The size of this radius depends on the density of the area around the central point. If there are a large number of hits close to the central point, the radius can be small. The fewer hits near the center, the larger the radius will be.

Ranking effect: Radius-based filtering creates a circle within which all results fall. It also creates a ranking based on the distance from that point - records closest to the central point are ranked higher than records further away.

Increasing Geo Distance

The default is to stop finding records after approximately 1000 records are found. This can mean that the radius of the circle can be quite small in dense areas. Imagine the number of cafés in Paris, 1000 would not be enough. You can override this by forcing the radius to be larger. This can be done either by using aroundRadius or minimumAroundRadius.

This override only applies to radius-based searches, not area-based ones like rectangles and polygons.

Filter inside rectangle/polygonal area

Results can be restricted to a given area by setting geometric boundaries (rectangles or odd-shaped polygons). 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.

Ranking effect: Filtering within or around an area doesn’t have any impact on the ranking of results. Additionally, area-based geo search does not work in combination with the radius-based geo search. There is no “central point” when creating areas of rectangles or polygons; hence, all results within the area are ranked equally.

Geographical Ranking

Geo ranking is based on the distance between the geolocation in the search query and the best matching geolocation in the record. For example, 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.

Geo in the Ranking Formula

For Geo ranking to function, it needs to be present in the ranking formula. The ranking formula contains a Geo criterion which by default is the second ranking criteria in the formula.

Additionally, this criterion is only meaningful when records contain the _geoloc attribute with the corresponding lat and lng properties. Otherwise, it has no ranking effect on records with no geo coordinates.

Changing Precision

By default, ranking is based on 1-meter distances. This means that records of 1-meter distance from a central point are ranked higher than records of 2-meter distances, and so on. This might not always be useful: imagine looking for the best restaurants within walking distance, 200-meter intervals would be more reasonable. Precision changes this.

Displaying results on a map

You can use the lat/lng values in your results to plot each record on a map. Check out our tutorial on how to do that.

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.