How to implement geolocation, a way to increase the relevance of search results

About Geolocation

To provide search results customized to the user's location, add geolocation functionality. With geolocation, a query can include not only the target search terms but also latitude and longitude data pinpointing the location of the person submitting the search. Searchify can use this information to provide search results related to that location.

Why Use Geolocation?

For some types of search results, the location of the person doing the search matters. A search for "coffee shop" or "plumber" is most likely not an abstract or academic one, but a practical search for an immediate need. If you know the location from which a query is submitted, you can potentially use that information to provide more useful search results. Finding a nearby place to get coffee, or a local plumber to fix a broken water pipe, is the result most likely to make users happy.

You might want to use location data as a ranking signal for every query. Alternatively, you can let the user decide whether location is important by providing a special UI control, such as a "Find Near Me" button or a Settings checkbox, and run the location-based query only when the user selects to do so.

How It Works

Geolocation is performed in several parts:

• Index: a location (latitude and longitude) can be associated with each document in the index. The latitude and longitude are stored in the index as document variables. Location data can be associated with all or only some of the documents in the index.
• Scoring function: a built-in distance scoring function can be applied to any query to calculate the distance between the user's location and the lat/long point stored for a document.
• Query: in addition to the scoring function, pass the user's location in the query by including lat/long values as query variables. With this data, the user's location can be compared to the document location.
• User interface: You might already know the user's location: perhaps your users are authenticated and you have stored profiles for them, you are using IP location software, or your users are accessing your application through GPS-enabled devices. If not, you need to provide a way for the user to specify a location (typically using a postal code or street address). By adding a little code to convert locations into lat/long coordinates, your application is ready to put location-based result ranking into effect.

Quick Start: Copy & Paste

Tweak the following code snippets for your needs, and you're ready to go

Before you start

• • 
  • 
  • 
  • 

  For Ruby environments we provide a gem that handles all the REST calls for you in a very Ruby-fashioned way.

  • Download the Ruby client if you have not already done so.
  • Know your index's public URL. You'll need it to instantiate the client. Find the public URL on the Dashboard.

  For Python environments we provide a package that handles all the REST calls for you. You can install it with Pip or download the library:

  • Download the Python client if you have not already done so.
  • Know your index's public URL. You'll need it to instantiate the client. Find the public URL on the Dashboard.

  For Php environments we provide a client that handles all the REST calls for you. Download a file that comes with the library ready to use.

  • Download the PHP client if you have not already done so.
  • Know your index's public URL. You'll need it to instantiate the client. Find the public URL on the Dashboard.

  For Java environments we provide a basic API client that handles all the REST calls for you and translates the responses to simple Java objects.

  • Download the Java client if you have not already done so.
  • Know your index's public URL. You'll need it to instantiate the client. Find the public URL on the Dashboard.

Add Lat/Long Data to the Documents

For those documents in your index that can be associated with a particular geographic location, store that location as a pair of document variables: one to store the latitude, and one to store the longitude.

The following code shows how to add latitude and longitude data to documents in the index, using the addDocument() method from the Java client library. The latitude and longitude values are expressed in degrees, as floating point numbers. The location used for this example is Buenos Aires, Argentina:

lat = -34.70549341022545
lon = -58.359375

variables = { 
              0 => lat,
              1 => lon
            }

index.document(docid).add(fields, :variables => variables)

lat = -34.70549341022545
lon = -58.359375

variables = { 0: lat, 1: lon }
 
index.add_document(id, fields, variables=variables)

$lat = -34.70549341022545;
$lon = -58.359375;
 
$variables = array('0'=>$lat, '1'=>$lon);

$index->add_document($doc_id, $fields. $variables);

Float lat = -34.70549341022545f;
Float lon = -58.359375f;

Map variables = new HashMap();
variables.put(0, lat);
variables.put(1, lon);

index.addDocument(docId, fields, variables);

Define Distance Scoring Function

Searchify provides a built-in function that you can use to calculate the distance between two points. Two versions are provided, miles() and km(), for calculating distance in either miles or kilometers. For details on the function syntax, see Scoring Function Formulas.

The following example shows how to use a distance function in the definition of custom scoring function number 5. The inclusion of the negative sign will cause this function to rank search results from shortest distance to longest.

index.functions(5, "-miles(d[0], d[1], q[0], q[1])").add

index.add_function(5, '-miles(d[0], d[1], q[0], q[1])')

$index->add_function(5, "-miles(d[0], d[1], q[0], q[1])");

index.addFunction(5, "-miles(d[0], d[1], q[0], q[1])");

Specify Location as a Query Variable

To pass the geolocation of a particular user in a search query, use query variables. The following code shows how to include both the distance scoring function and the lat/long data as parameters to a query:

index.search(query, 
             :function => 5, 
             :var0 => latitude, 
             :var1 => longitud)

variables = { 0: latitude, 1: longitude }

index.search(query, 
             scoring_function=5,
             variables=variables)

# Unsupported by current PHP client

results = index.search(Query.forString(query)
                       .withScoringFunction(5)
                       .withQueryVariable(0, latitude)
                       .withQueryVariable(1, longitude));

More Information

• Scoring Functions Tutorial