Geolocation search

Overview

Fess can execute searches with geographical ranges specified for documents containing latitude and longitude location information. Using this feature, you can search for documents within a certain distance from a specific point, or build search systems integrated with map services like Google Maps.

Use Cases

Geolocation search can be utilized for purposes such as:

store search: search for stores near the user’s current location
Real Estate search: search for properties within a certain distance from specific stations or facilities
Event search: search for event information around specified locations
Facility search: search for tourist spots or public facilities nearby

Configuration

Index Generation settings

Location Field Definition

In Fess, location is defined as a standard field for storing location information. This field is configured as Opensearch’s geo_point type.

Location Registration Format

When generating indexes, set latitude and longitude separated by commas in the location field.

Format:

latitude,longitude

Example:

45.17614,-93.87341

Note

specify latitude in the range -90 to 90, and longitude in the range -180 to 180.

Data store Crawl Configuration Example

When using data store crawl, set latitude and longitude in the location field from data sources with location information.

Example: Retrieving from Database

sELECT
    id,
    name,
    address,
    CONCAT(latitude, ',', longitude) as location
FROM stores

Adding Location Information via script

You can also dynamically add location information to documents using the script feature in crawl configuration.

// set latitude and longitude in location field
doc.location = "35.681236,139.767125";

search settings

To execute geolocation search, specify the search center point and range in request parameters.

Request Parameters

Parameter Name	Description
`geo.location.point`	Latitude and longitude of the search center point (comma-separated)
`geo.location.distance`	search radius from center point (with unit)

Distance Units

The following units can be used for distance:

km: kilometers
m: meters
mi: miles
yd: yards

search Examples

Basic search

To search for documents within a 10km radius from Tokyo station (35.681236, 139.767125):

http://localhost:8080/search?q=search keyword&geo.location.point=35.681236,139.767125&geo.location.distance=10km

Nearby search

To search within 1km from the user’s current location:

http://localhost:8080/search?q=ramen&geo.location.point=35.681236,139.767125&geo.location.distance=1km

sorting by Distance

To sort search results by distance, use the sort parameter.

http://localhost:8080/search?q=convenience store&geo.location.point=35.681236,139.767125&geo.location.distance=5km&sort=location.distance

API Usage

Geolocation search can also be used with the JsON API.

curl -X POsT "http://localhost:8080/json/?q=hotel" \
  -H "Content-Type: application/json" \
  -d '{
    "geo.location.point": "35.681236,139.767125",
    "geo.location.distance": "5km"
  }'

Field Name Customization

Changing Default Field Name

To change the field name used for geolocation search, change the following setting in fess_config.properties.

query.geo.fields=location

To specify multiple field names, separate them with commas.

query.geo.fields=location,geo_point,coordinates

Implementation Examples

Web Application Implementation

Example of retrieving current location and searching using Javascript:

// Get current location using browser's Geolocation API
navigator.geolocation.getCurrentPosition(function(position) {
    const latitude = position.coords.latitude;
    const longitude = position.coords.longitude;
    const distance = "5km";

    // Build search URL
    const searchUrl = `/search?q=&geo.location.point=${latitude},${longitude}&geo.location.distance=${distance}`;

    // Execute search
    window.location.href = searchUrl;
});

Google Maps Integration

Example of displaying search results as markers on Google Maps:

// Initialize map
const map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: 35.681236, lng: 139.767125},
    zoom: 13
});

// Execute geolocation search with Fess API
fetch('/json/?q=store&geo.location.point=35.681236,139.767125&geo.location.distance=5km')
    .then(response => response.json())
    .then(data => {
        // Display search results as markers
        data.response.result.forEach(doc => {
            if (doc.location) {
                const [lat, lng] = doc.location.split(',').map(Number);
                new google.maps.Marker({
                    position: {lat: lat, lng: lng},
                    map: map,
                    title: doc.title
                });
            }
        });
    });

Performance Optimization

Index Configuration Optimization

When handling large amounts of location data, optimize index configuration.

Check location field settings in app/WEB-INF/classes/fess_indices/fess.json.

"location": {
    "type": "geo_point"
}

Limiting search Range

Considering performance, it is recommended to set the search range to the minimum necessary.

Wide-range searches (50km or more) may take time to process
set appropriate ranges according to use case

Troubleshooting