Geo-Filtering Quickstart

Geo-filtering gives your app the ability to filter search results by a geographic location (only Earth coordinates are supported currently 🌎). This allows you to surface both semantically relevant and location-aware search results to your users when geography is important, such as brick-and-mortar store searches, concert event searches, and job searches.

If you already have a Private Beta account, go check it out in your Console now! If you aren’t, jump on the waitlist — we’re still onboarding developers as fast as we can, and we’ll let you know when your account is ready!

To implement Geo-Filtering with Objective Search, follow these steps:

Add data: Add data to the Object Store
Create Index: Build an Index using the data
Search Index: Querying the Index to get results

Setup

For this Quickstart, we'll use the Python SDK, but you can follow along in TypeScript by grabbing our Typescript library. Begin by obtaining an API key and installing the SDK:

To get an API key, sign up.

pip3 install --upgrade objective-sdk

Adding data

Implementing geo-filtering is straightforward. Begin by adding Objects to the Object Store that include geographic coordinates. Consider this example where we build a brick-and-mortar restaurant search platform:

from objective import Objective

client = Objective(api_key="YOUR_API_KEY")

objects = [
    {
        "store_name": "Joan's Giant Burgers",
        "store_photo": "https://t4.ftcdn.net/jpg/01/98/94/15/240_F_198941587_KMXpll1r21FkaST48v5koKT1e7RoZsLj.jpg",
        "coordinates": {
            "lat": 51.524000,
            "lon": -0.158610
        }
    }
    # Additional objects...
]

for obj in objects:
    client.objects.create(body=obj)

Building an Index

Build an index out of the Objects pushed to the API. Configure your Index to recognize the coordinates field as filterable and designate it as a 'geo' field:

import time
from objective.types.index_create_params import Configuration, ConfigurationIndexType, ConfigurationFields

index = client.indexes.create(
       configuration=Configuration(
           index_type=ConfigurationIndexType(
               name="multimodal",
           ),
           fields=ConfigurationFields(
               searchable={
                   "allow": [
                     "store_name",
                   ],
               },
               crawlable={
                   "allow":[
                    "store_photo",
                   ]
               },
               filterable={
                  "allow": [
                    "coordinates",
                   ]
               },
               types={
                   "coordinates": "geo",
               },
           )
       ),
   )

while not client.indexes.status(index_id=index.id).status.ready:
    time.sleep(1)

print(f"Index {index.id} is ready for queries!")

Querying results

Geo-filtering syntax breaks down into the following format: {field_name}:@{latitude},{longitude},{distance_in_meters}. To query within a specific radius:

from objective import Client as ObjectiveClient

client = Objective(api_key="YOUR_API_KEY")

search_response = client.indexes.search(
    index_id="INSERT_INDEX_ID_HERE",
    query="burger restaurant",
    object_fields="*",
    filter_query="coordinates:@51.523160,-0.158070,810",
)

print(search_response.to_json())

In our scenario, we’re searching for dining options within 810 meters of 221B Baker St., London (with coordinates 51.523160, -0.158070,810). Imagine finding Joan’s Giant Burgers just a short walk away!

{
    "results": [
        {
            "id": "obj_07bcc8ecc1ed42e3b46c87404ab21122",
            "object": {
                "store_photo": "https://t4.ftcdn.net/jpg/01/98/94/15/240_F_198941587_KMXpll1r21FkaST48v5koKT1e7RoZsLj.jpg",
                "store_name": "Joan's Giant Burgers",
                "coordinates": {
                    "lat": 51.524,
                    "lon": -0.15861
                }
            }
        }
    ],
    "pagination": {
        "pages": 1,
        "page": 1
    }
}

Follow-Up Experiment

Try adjusting the distance in your search to 100 meters. Let us know your findings!

Explore More Resources:

managing data via the Object Store APIs
configuring indexes via the Index APIs
searching and filtering via the Search API

For assistance or inquiries, contact us at [email protected].