InBetween
Search

Search Endpoint Overview

The search route is the primary way of discovering locations that will fit your users' location, wants, and needs

The Search API is InBe's core endpoint for intelligent location discovery. Instead of just finding places "near me", it matches venues to your users' specific location, context, preferences, and constraints. It's a powerful endpoint, providing many variables that you can use to tailor results for your needs. We will be adding more features and improvements over time, but our plan is to continue to support this endpoint (v1) even after we have released v2.

Caching

If you are caching the venue details, you should only cache the venue ID. Do not cache the full venue details response, as the data changes frequently and must always be fetched fresh for accuracy and compliance.

How it works

Request structure

API key

These docs are under the impression that you have your API key, and you are including it in the header of each request.

Every search request requires at least one location and can include sophisticated preferences, search modes, and pagination controls.

Basic search request body
const :  = {
  : [{ : 51.5081, : -0.1278 }],
  : {
    : "POINT",
    : 500, 
  },
  : {
    : ["restaurant"],
    : ["vegan"],
  },
};

maxDistance is in metres.
Basic search request with cURL
curl -X POST "https://api.inbe.app/v1/search/" \
  -H "Content-Type: application/json" \
  -H "API-Key: YOUR_API_KEY" \
  -d '{
    "locations": [{ "lat": 51.5081, "lon": -0.1278 }],
    "mode": {
      "mode": "POINT",
      "maxDistance": 500
    },
    "preferences": {
      "establishmentFilters": ["restaurant"],
      "catersFilters": ["vegan"]
    }
  }'
Basic search request with Python
import requests

url = "https://api.inbe.app/v1/search/"
headers = {
    "Content-Type": "application/json",
    "API-Key": "YOUR_API_KEY"
}
data = {
    "locations": [{"lat": 51.5081, "lon": -0.1278}],
    "mode": {
        "mode": "POINT",
        "maxDistance": 500
    },
    "preferences": {
        "establishmentFilters": ["restaurant"],
        "catersFilters": ["vegan"]
    }
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
Basic search request with Go
package main

import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)

func main() {
url := "https://api.inbe.us/v1/search"
payload := map[string]any{
"locations": []map[string]float64{
{"lat": 51.5081, "lon": -0.1278},
},
"mode": map[string]any{
"mode": "POINT",
"maxDistance": 500,
},
"preferences": map[string]any{
"establishmentFilters": []string{"restaurant"},
"catersFilters": []string{"vegan"},
},
}

body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("API-Key", "YOUR_API_KEY")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
	panic(err)
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
fmt.Println(string(respBody))

}

const response = await fetch("https://api.inbe.app/v1/search/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "API-Key": " YOUR_API_KEY"
  },
  body: JSON.stringify({
    locations: [{ lat: 51.5081, lon: -0.1278 }],
    mode: {
      mode: "POINT",
      maxDistance: 500
    },
    preferences: {
      establishmentFilters: ["restaurant"],
      catersFilters: ["vegan"]
    }
  })
});

const data = await response.json();
console.log(data);

Caching

If you are caching the venue details, you should only cache the venue ID. Do not cache the venue details, as the data changes frequently and must always be fetched fresh for accuracy and compliance.

Key components

Locations

Define where to search from. Support single points, multiple users, paths, and custom weighting.

Mode

Control search behaviour: POINT (radius-based) or PATH (route-following) with distance limits.

Preferences

Fine-tune results with establishment types, dietary needs, genres, and more.

Pagination

Control result count and offset for large result sets.

Search modes

POINT mode

Radius-based search around a defined location based on the weight of the locations provided in the request. This is particularly useful when people are meeting up and you want to find venues that are convenient for everyone.

PATH mode

Find venues along a route of multiple locations within a defined distance of the route. This is perfect for finding venues along a route, like a tour guide or journey planning app.

Search corridor

Real-world examples

Find romantic spots between two people
const :  = {
  : [
    { : 51.5072, : -0.1276, : 50 }, 
    { : 51.5154, : -0.1419, : 50 }, 
  ],
  : {
    : "POINT",
    : 750,
  },
  : {
    : ["restaurant"],
    : ["romantic", "conversation"],
    : { : "OPEN", : "2025-10-18T19:30:00Z" },
  },
};

Because the weights are equal, the midpoint will be the average of the two locations
Find coffee shops convenient for everyone
const :  = {
  : [
    { : 51.5072, : -0.1276, : 30 },
    { : 51.5154, : -0.1419, : 40 },
    { : 51.5034, : -0.1195, : 30 },
  ],
  : {
    : "POINT",
    : 1000,
  },
  : {
    : ["coffee_shop"],
    : "PREFER_INDEPENDENT",
    : { : "OPEN" }, 
  },
};

Not setting atTime in openingConditions will find places that match the state at the current time
Find attractions along a route
const :  = {
  : [
    { : 51.5072, : -0.1276 }, 
    { : 51.5154, : -0.1419 }, 
    { : 51.5034, : -0.1195 }, 
  ],
  : {
    : "PATH", 
    : 50,
  },
  : {
    : ["family_friendly"],
    : { : "OPEN" },
  },
};

For mode PATH, maxDistance sets the search width along the route. Weights aren't needed.

Response format

Search responses include rich venue data, travel times from each location, and match quality scores.

Search response structure
{
  "centerPoint": { "Lat": 51.514580503047924, "Lon": -0.10930463283725232 },
  "radius": 500,
  "establishments": [
    {
      "id": "192454d3-0ef0-42d1-b7ac-96R46s61ebafd",
      "name": "THE LEAKY CAULDRON LIMITED",
      "displayName": "The Leaky Cauldron",
      "formattedAddress": "1 Diagon Alley, London, England, WC2E 9MB",
      "location": {
        "type": "Point",
        "coordinates": [51.512440569276464, -0.08397694587337928]
      },
      "websiteUri": "https://www.theleakycauldron.co.uk",
      "contactEmail": "info@theleakycauldron.co.uk",
      "contactNumber": "020 7240 0000",
      "description": "The Leaky Cauldron caters for a different audience than the other establishments in the area. It is known for its traditional British pub food and its cozy atmosphere and occasional sightings of celebrities.",
      "primaryGenre": "Pub",
      "additionalGenres": ["British", "Cozy", "Brew-pub"],
      "wordOnTheStreet": "Many visitors report strange goings on such as people going out the back and never coming back.",
      "isOpen": true,
      "isChain": false,
      "regularOpeningHours": [
        {
          "days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
          "timeSlots": [
            {
              "open": "12:00",
              "close": "23:30",
              "isClosed": false,
              "closeNextDay": false
            }
          ]
        },
        {
          "days": ["Sat", "Sun"],
          "timeSlots": [
            {
              "open": "12:00",
              "close": "23:00",
              "isClosed": false,
              "closeNextDay": false
            }
          ]
        }
      ],
      "mainImageUrl": "https://yebvmotmofmfuddjbxiy.supabase.co/storage/v1/object/public/assets/LCInside.png",
      "logo": "https://yebvmotmofmfuddjbxiy.supabase.co/storage/v1/object/public/assets/LCLogo.png",
      "establishmentFlags": [
        "freeWifi",
        "servesCocktails",
        "servesFood",
        "servesAlcohol",
        "servesNonAlcohol"
      ],
      "catersFlags": [
        "crustaceanFree",
        "dairyFree",
        "eggFree",
        "fishFree",
        "glutenFree",
        "molluscFree",
        "vegan",
        "vegetarian",
        "wheatFree"
      ],
      "distanceMeters": 25.68498912,
      "matchScore": {
        "genreMatch": 1,
        "establishmentFiltersMatch": 1,
        "catersFiltersMatch": 1,
        "total": 1
      }
    }
    // Other establishments...
  ]
}

API Reference

Below is the complete OpenAPI specification for the Search endpoint:

POST
/v1/search/

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/v1/search/" \  -H "Content-Type: application/json" \  -d '{}'
{}

Next steps

Search Modes

Choose between POINT and PATH search behaviours.

Explore Preferences

Master filtering and preference matching for better results.

Analytics

Use our analytics to dig into what your users are looking for

Locations

This object enables you to define one to many locations. Depending on the properties you provide, you can find locations at a single point, along a path, or between points

On this page

How it worksRequest structureKey componentsSearch modesPOINT modePATH modeReal-world examplesResponse formatAPI ReferenceNext steps