The find endpoint allows you to search for specific venues by name or partial name matches. This is perfect for when users know exactly what they're looking for or want to find a particular establishment.

Endpoint details

GET /v1/find/

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.

Query parameters

search term (required)

The venue name or partial name to search for. Minimum 1 character.

lat (optional)

Latitude coordinate to centre the search around. If provided, results are ordered by proximity.

lon (optional)

Longitude coordinate to centre the search around. Must be provided with lat.

location (optional)

Human-readable location string (e.g., "London", "New York") for broader area searches.

maxDistanceMeters (optional)

Maximum search distance in meters. Defaults to 5,000m (5km).

Basic usage

GET /v1/find/?name=Starbucks

Request examples

const response = await fetch(
  "/v1/find/?name=Coffee&lat=51.5072&lon=-0.1276&maxDistanceMeters=2000",
);
const results = await response.json();

Response format

By name search response

{
  "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": 2609.23987766
    }
    // Other establishments...
  ],
  "searchQuery": "Strange Pub",
  "totalFound": 15,
  "searchLocation": {
    "Lat": 51.5074,
    "Lon": -0.1278
  },
  "maxDistanceMeters": 5000
}

Search strategies

Exact name matching

Use the full, exact name for precise results:

GET /v1/find/?name=The%20Ritz%20London

Partial name matching

Use partial names to find similar venues:

GET /v1/find/?name=The%20Ritz

Generic term search

If you are searching for a specific type of establishment, you should use the search endpoint and set the genre to your desired genre. If you use the find endpoint below, you will get results with 'Coffee' in the name.

GET /v1/find/?name=Coffee&lat=51.5072&lon=-0.1276

Real-world examples

Finding a specific pub

class Finder {
  async findNearby(
    lat: number,
    lon: number,
    searchTerm: string = "The Leaky Cauldron",
  ) {
    const params = new URLSearchParams({
      name: searchTerm,
      lat: lat.toString(),
      lon: lon.toString(),
      maxDistanceMeters: "2000",
    });
 
    const response = await fetch(`/v1/find/?${params}`);
    return await response.json();
  }
 
  async findInCity(city: string, searchTerm: string = "The Leaky Cauldron") {
    const params = new URLSearchParams({
      name: searchTerm,
      location: city,
    });
 
    const response = await fetch(`/v1/find/?${params}`);
    return await response.json();
  }
}

Best practice

Use meaningful search terms: "The Leaky Cauldron" is better than "The"
Provide coordinates when possible: Results are more relevant and ordered by proximity
Set appropriate distance limits: Don't search 5km unless necessary
Handle partial matches: Users often type partial names

By Search Term Endpoint