# Retrieve a list of venues

Returns a paginated list of venues available to the authenticated user or system.  This endpoint supports page-based pagination to efficiently retrieve large sets of results.

Endpoint: GET /venues
Version: 4.10.0
Security: Staging, Production

## Header parameters:

  - `X-Partner-Reference` (string)
    Required for Bookable Agents. Specifies the partner reference for whom the booking is being made.
This header must contain a valid partner reference when making requests with the agent:write scope.
    Example: "bottomlessbrunch.com"

  - `X-Correlation-ID` (string)
    An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.
Mirrored back in a response header.
    Example: "11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"

## Query parameters:

  - `venueName` (string)
    Filter venues by name. Supports partial matching (case-insensitive). Example: "dishoom" will match "Dishoom Covent Garden".
    Example: "dishoom"

  - `venueGroupName` (string)
    Filter venues by group or chain name. Supports partial matching (case-insensitive). Example: "gordon ramsay" will match all Gordon Ramsay restaurants.
    Example: "gordon ramsay"

  - `features` (array)
    Filter venues by features. Supports multiple values separated by commas. Available features include: dog_friendly, wifi, parking, wheelchair_accessible,  tv_sports, live_music, karaoke, pool_table, romantic, casual, family_friendly,  quiet, lively, italian, asian, vegetarian, seafood, etc.
    Example: ["dog_friendly","wifi","romantic"]

  - `content` (string)
    Filter venues by description content. Supports partial matching (case-insensitive). Searches within the venue's content/description field.
    Example: "bombay cuisine"

  - `productName` (string)
    Filter venues by product/experience name. Supports partial matching (case-insensitive). Searches within product names and experience names.
    Example: "dining room"

  - `bookingDays` (array)
    Filter venues by available booking days. Supports multiple values separated by commas. Use day names (monday, tuesday, wednesday, thursday, friday, saturday, sunday).
    Enum: "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"

  - `area` (string)
    Filter venues by area/location. Supports partial matching (case-insensitive). Searches within the venue's area field.
    Example: "covent garden"

  - `city` (string)
    Filter venues by city. Supports partial matching (case-insensitive).
    Example: "london"

  - `street` (string)
    Filter venues by street address. Supports partial matching (case-insensitive). Searches within the venue's street address field.
    Example: "upper st martin"

  - `venueTypes` (array)
    Filter venues by type. Supports multiple values separated by commas. Available types include: restaurant, bar, cafe, hotel, pub, club, etc.
    Example: ["restaurant","bar"]

  - `date` (string)
    Filter venues by booking rules for a specific date. Format: ISO 8601 (YYYY-MM-DD). Returns venues that accept bookings on the specified date according to their booking rules. When both 'date' and 'bookingDays' filters are provided,  the 'date' filter takes precedence and overrides the 'bookingDays' filter.
    Example: "2025-10-15"

  - `time` (string,null)
    Filter venues by booking rules at a specific time. Format: 24-hour (HH:MM). Returns venues that accept bookings at the specified time according to their booking rules.  Must be used in conjunction with the date parameter.
    Example: "19:30"

  - `pageNumber` (integer)
    The index of the page to return (default is 1).

  - `pageSize` (integer)
    The number of items to return per page (default is 20, max is 100).

  - `sortBy` (string)
    The field to sort results by. Defaults to 'Default' (composite ID ordering).
- default: Sort by composite ID (venue_group_id, rms_id, venue_id)
- name: Sort venues alphabetically by name
- city: Sort venues by city name, then by venue name
- area: Sort venues by area, then by venue name
- venueGroup: Sort venues by venue group name (requires venueGroupName filter)
- relevance: Sort by semantic similarity using vector embeddings (requires at least one embedding filter: venueName, content, or features with semantic search enabled)
    Enum: "default", "name", "city", "area", "venueGroup", "relevance"

  - `sortDirection` (string)
    The direction to sort results. Defaults to 'ASC'.
- ASC: Ascending order (A-Z, 0-9, most similar to least similar for relevance)
- DESC: Descending order (Z-A, 9-0, least similar to most similar for relevance)
    Enum: "ASC", "DESC"

## Response 200 fields (application/json):

  - `meta` (object)

  - `meta.totalItems` (integer)
    The total number of items available.

  - `meta.totalPages` (integer)
    The total number of pages.

  - `meta.currentPage` (integer)
    The current page number based on limit and offset.

  - `meta.limit` (integer)
    The number of items returned per page.

  - `data` (array)
    A list of venue records for the current page.

  - `data.id` (string, required)
    Unique identifier for the venue.

  - `data.name` (string, required)
    The name of the venue.

  - `data.content` (string)
    Description or additional content about the venue.

  - `data.phone_number` (string)
    The contact phone number of the venue.

  - `data.website` (string)
    The official website of the venue.

  - `data.reservable` (boolean)
    Indicates if the venue can be reserved.

  - `data.location` (object)

  - `data.location.area` (string)
    The general area where the venue is located Can be more than one separated by |.

  - `data.location.city` (string)
    The city where the venue is located.

  - `data.location.lat` (number)
    The latitude coordinate of the venue.

  - `data.location.lng` (number)
    The longitude coordinate of the venue.

  - `data.location.street` (string)
    The street address of the venue.

  - `data.location.postCode` (string)
    The postal code of the venue.

  - `data.location.gPlace` (string)
    The Google Place ID associated with the venue.

  - `data.types` (array)
    A list of types that categorize the venue.

  - `data.photos` (array)
    A collection of photo URLs representing the venue.

  - `data.updated_at` (string)
    Timestamp when the venue was last updated.

  - `data.products` (array)
    List of products available at the venue.

  - `data.products.compositeId` (string, required)
    Unique identifier of the venue/product, used by other services (availability, booking, amendment)..

  - `data.products.productName` (string)
    Name of the booking product.

  - `data.products.timeInterval` (integer)
    The valid time options per booking for this product.

  - `data.products.bookingRules` (object)

  - `data.products.bookingRules.monday` (object,null)
    Booking rule information.

  - `data.products.bookingRules.monday.from` (string,null)
    Starting time for which bookings are allowed (ISO8601 hh:mm format).

  - `data.products.bookingRules.monday.to` (string,null)
    Ending time for which bookings are allowed (ISO8601 hh:mm format).

  - `data.products.bookingRules.monday.bookingCutoff` (string,null)
    The cutoff time after which bookings are no longer accepted. Accepts time in ISO 8601 hh:mm format or as a duration (e.g., -60 for 2 hours).

  - `data.products.bookingRules.monday.minDuration` (integer,null)
    The minimum duration in minutes allowed for the booking

  - `data.products.bookingRules.monday.maxDuration` (integer,null)
    The maximum duration in minutes allowed for the booking

  - `data.products.bookingRules.monday.minPartySize` (integer,null)
    The minimum partySize allowed for the booking

  - `data.products.bookingRules.monday.maxPartySize` (integer,null)
    The maximum partySize allowed for the booking

  - `data.products.bookingRules.monday.notes` (string,null)
    Optional notes or remarks for the booking.

  - `data.products.bookingRules.tuesday` (object,null)
    Booking rule information.

  - `data.products.bookingRules.wednesday` (object,null)
    Booking rule information.

  - `data.products.bookingRules.thursday` (object,null)
    Booking rule information.

  - `data.products.bookingRules.friday` (object,null)
    Booking rule information.

  - `data.products.bookingRules.saturday` (object,null)
    Booking rule information.

  - `data.products.bookingRules.sunday` (object,null)
    Booking rule information.

  - `data.products.bookingOverrides` (array)

  - `data.products.bookingOverrides.id` (string, required)
    Unique identifier for the booking override
    Example: "5e33079d6e4fb3019d08d127"

  - `data.products.bookingOverrides.date_from` (string,null)
    Start date for the override rule (inclusive)
    Example: "2020-04-10"

  - `data.products.bookingOverrides.date_to` (string,null)
    End date for the override rule (inclusive)
    Example: "2020-04-10"

  - `data.products.bookingOverrides.booking_available` (boolean,null)
    Whether bookings are available during this period
    Example: true

  - `data.products.bookingOverrides.bookings_from` (string,null)
    Start time for accepting bookings (HH:mm format)
    Example: "11:00"

  - `data.products.bookingOverrides.bookings_to` (string,null)
    End time for accepting bookings (HH:mm format)
    Example: "15:00"

  - `data.products.bookingOverrides.min_duration` (integer,null)
    Minimum booking duration in minutes
    Example: 120

  - `data.products.bookingOverrides.max_duration` (integer,null)
    Maximum booking duration in minutes
    Example: 120

  - `data.products.bookingOverrides.min_people` (integer,null)
    Minimum number of people allowed per booking
    Example: 1

  - `data.products.bookingOverrides.max_people` (integer,null)
    Maximum number of people allowed per booking
    Example: 24

  - `data.products.bookingOverrides.auto_confirm_max` (integer,null)
    Maximum number of people for automatic booking confirmation
    Example: 14

  - `data.products.bookingOverrides.booking_notes` (string,null)
    Special notes or conditions for bookings during this period
    Example: "£10 per person card authentication required to confirm your booking. Should you wish to cancel the booking, please let us know within 48 hours of your reservation otherwise your card will be charged at £10 per person."

  - `data.products.operatorAvailabilityRules` (array)
    List of operator availability rules for the product

  - `data.products.operatorAvailabilityRules.name` (string, required)
    Name of the availability rule
    Example: "Weekend Availability Rule"

  - `data.products.operatorAvailabilityRules.description` (string,null)
    Description of the availability rule
    Example: "Rule that manages availability during weekends"

  - `data.products.operatorAvailabilityRules.ruleType` (string, required)
    Type of availability rule:
- date_range: Rules that apply to a continuous date range
- recurring: Rules that repeat based on patterns (days of week, months)
- time_based: Rules that apply to specific time periods within a day
- specific_dates: Rules that apply to explicitly listed dates
    Enum: "date_range", "recurring", "time_based", "specific_dates"

  - `data.products.operatorAvailabilityRules.ruleData` (object, required)

  - `data.packages` (array)
    List of packages available at the venue.

  - `data.packages.id` (string, required)
    Unique identifier for the package
    Example: "5888a5afc71620e04002d5bb"

  - `data.packages.name` (string, required)
    Package name
    Example: "*Pan roasted Padron peppers (V)"

  - `data.packages.price` (number, required)
    Package price
    Example: 5.57

  - `data.packages.description` (string)
    Detailed package description
    Example: "5 items per guest: Salmon & celeriac on rye, Buttermilk fries chicken..."

  - `data.packages.type` (string, required)
    Main package type
    Example: "food"

  - `data.packages.sub_type` (string)
    Package subtype (mainly for type=food)
    Example: "starter"

  - `data.packages.diet_types` (array)
    Supported diet types
    Example: ["Vegetarian","Vegan"]

  - `data.packages.allergens` (array)
    List of allergens present
    Example: ["Gluten","Milk"]

  - `data.packages.configurable_options` (array)
    Configurable options for the package

  - `data.packages.configurable_options.label` (string)
    Option label
    Example: "How Would You Like It Cooked ?"

  - `data.packages.configurable_options.description` (string)
    Option description
    Example: "Let us know how you like your steak cooked?"

  - `data.packages.configurable_options.min` (integer)
    Minimum number of selections required
    Example: 1

  - `data.packages.configurable_options.max` (integer)
    Maximum number of selections allowed
    Example: 1

  - `data.packages.configurable_options.values` (array)
    Available values for the option

  - `data.packages.configurable_options.values.label` (string, required)
    Value label
    Example: "Rare"

  - `data.packages.configurable_options.values.price_change` (number)
    Price change for this value
    Example: 2.5

  - `data.packages.configurable_options.values.diet_types` (array)
    Diet types supported by this value
    Example: ["Vegetarian","Vegan"]

  - `data.packages.configurable_options.values.allergens` (array)
    Allergens added by this value
    Example: ["Milk"]

  - `data.packages.configurable_options.values.removes_allergens` (array)
    Allergens removed by this value
    Example: ["Gluten"]

  - `data.menus` (array)
    List of menus available at the venue.

  - `data.menus.id` (string, required)
    Unique identifier for the menu
    Example: "68a5f2eee07ae30fcd653b03"

  - `data.menus.name` (string, required)
    Menu name
    Example: "Set Menu"

  - `data.menus.description` (string)
    Detailed menu description
    Example: "A choice of 2 or 3 courses from our set menu. Disclaimer:..."

  - `data.menus.items` (array, required)
    The available options for the menu

  - `data.menus.items.packageId` (string, required)
    The ID of the package that composes the menu item
    Example: "62c6c9f532c7cc7e4265dfdc"

  - `data.menus.items.type` (string)
    The menu item type (e.g. food, drink, etc.)
    Example: "food"

  - `data.opening_times` (object)
    Opening times for the venue, including weekly schedule and specific date overrides.
    Example: {"monday":{"status":true,"open":"10:00","close":"23:00","notes":"","private_hire":false},"tuesday":{"status":true,"open":"10:00","close":"23:00","notes":"","private_hire":false},"2025-12-25":{"status":false,"open":"","close":"","notes":"Closed for Christmas"}}

  - `data.is_active` (boolean)
    Indicates if the venue is currently active.

  - `data.created_at` (string)
    Timestamp when the venue was created.

## Response default fields (application/json):

  - `type` (string)
    A URI reference [rfc9457] that identifies the problem type. This specification encourages that, when dereferenced, it provides human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".

  - `title` (string, required)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

  - `status` (integer, required)
    The HTTP status code [rfc9457, Section 3.1.12] generated by the origin server for this occurrence of the problem.

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.