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 their 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)
• Sort around a set of latitude and longitude coordinates
• Sort around the user’s location based on their IP address (IPv4 only)

Enabling Geo Search by adding geolocation data to records

To enable the Geo Search feature, geolocation data is required in your records. You must provide geolocation data as a _geoloc attribute that contains the latitude and longitude as 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 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 geographical information you can do two things:

1. Geographical Filtering
2. Geographical Ranking

Geographical filtering and sorting

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’s to send along with the query
• or it’s 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 many 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 the distance to find results in

The default behavior is to stop finding records after approximately 1,000 matching records. Therefore, the radius of your search could be quite small in dense areas. Imagine the number of cafés in Paris, 1,000 matching records wouldn’t be enough to list them all. You can override this behavior by forcing a larger radius, either by using aroundRadius or minimumAroundRadius. Note that even with a larger radius, the results still match any applied query or filter. The number of results can therefore be low if the query or filters are restrictive, even if you set a huge radius.

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

Filtering inside rectangular or polygonal areas

You can restrict results to a given area by setting geometric boundaries in either the shape of a rectangle or other polygon. 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 doesn’t work in combination with the radius-based Geo Search. When filtering on rectangular or polygonal areas, the engine considers all results within the area geographically equal.

Don’t mix bounding boxes and polygons

You can’t use insideBoundingBox and insidePolygon together. If you provide both, only insideBoundingBox actions will run.

For example, you have created an app for a chain of restaurants in the South West US and you want to show the locations of your restaurants on a map:

• You use a rectangular bounding box to display the South West region of the US. Blue pins indicate cities where you have restaurants.
• As the user zooms in, you want polygons to mark the boundaries of these cities. Red pins mark the locations of individual restaurants within the polygons.

Since insideBoundingBox takes precedence, you only see blue pins on the map.

For this reason, it isn’t recommended to use a mix of bounding boxes and polygons.

Geographical ranking

Geographical 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 criterion in the ranking formula

For geographical 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. This criterion is only meaningful when records contain the _geoloc attribute with the corresponding lat and lng properties.

Changing precision

By default, ranking is based on 10-meter distances, which is the smallest precision Algolia provides. This means that records of 10-meter distance from a central point are ranked higher than records of 20-meter distances, which are ranked higher than records of 30-meter distances, etc. 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 latitude and longitude values in your results to plot each record on a map. Check out the tutorial on how to display your results in Google Maps using InstantSearch.