InBe Docs

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 meters.

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 behavior: 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 for 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 that are 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" },
  },
};
 
Becuase the weights are equal, the midpoint will be the average of the two locations

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",
        "molluskFree",
        "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:

Next steps

Search Modes

Choose between POINT and PATH search behaviors.

Explore Preferences

Master filtering and preference matching for better results.

On this page