Home/ Items & Experiences

Items & Experiences

APIs for browsing, searching, and retrieving detailed information about experiences. The Get Single Item API is the most critical — it contains all values needed for the booking flow.

# Get Items (Paginated List)

Main browse/listing API with rich filtering, geo-sorting, and full-text search. Powers home page carousels, category pages, and search results.

GET{{base_url}}/items

Bearer Token Required

Query Parameters

Field	Type	Required	Description
page	number	REQUIRED	Page number. Start with `1`.
limit	number	REQUIRED	Items per page. Recommended: `20`.
latitude	number	OPTIONAL	User latitude for geo-sorting and distance calculation
longitude	number	OPTIONAL	User longitude for geo-sorting
category	string	OPTIONAL	Category name from GET /categories. Comma-separated for multiple. Example: `Tours & Sightseeing`
subCategory	string	OPTIONAL	Sub-category name from GET /sub-categories
title	string	OPTIONAL	Text search on item title
cityCode	string	OPTIONAL	ONDC city code from GET /city. Example: `std:011`
date	string	OPTIONAL	ISO date for availability. Example: `2026-03-01T00:00:00.000Z`
priceMin	number	OPTIONAL	Minimum price in INR
priceMax	number	OPTIONAL	Max price. Get global max from GET /get-min-max-price
minRating	number	OPTIONAL	Minimum rating 0–5
sort	string	OPTIONAL	Sort: `price-low-to-high` \| `price-high-to-low` \| `distance` \| `relevance` \| `just-launched`
trending	bool	OPTIONAL	`true` to fetch trending items for home carousel
topExperiences	bool	OPTIONAL	`true` for the "Top Experiences" section
isRecentlyViewed	bool	OPTIONAL	`true` with `userId` to show user's recently viewed items
userId	string	OPTIONAL	User UUID — required when using `isRecentlyViewed=true`
maxDistance	number	OPTIONAL	Max search radius in km. Default: `300`
providerId	string	OPTIONAL	Filter by provider ID from GET /providers

Response — 200 OK

{
  "data": {
    "items": [
      {
        "id": "019be498-69f3-7c9d-8377-ba96b37931e6",  // Use in GET /item/slug/:id
        "slug": "private-full-day-old-and-new-delhi-tour",
        "title": "Private Full Day Old & New Delhi Tour",
        "description": "Explore Delhi's heritage...",
        "rating": 4.5,
        "reviewCount": 12,
        "price": "6000",          // Starting price in INR, or "Free"
        "image": "https://cdn.rzervit.com/...",
        "location": "NEW DELHI",
        "category": "Tours & Sightseeing",
        "cityCode": "std:011",
        "distance": "2.36"         // km — only present if lat/lng was passed
      }
    ],
    "total": 42    // Total matching items — use for pagination (total ÷ limit)
  }
}

Pagination: Use total ÷ limit for total pages. Results are cached for 5 hours per unique filter combination.

# Get Single Item by Slug

The Item Detail Page (PDP) API. Returns complete data including packages, tickets, pricing, bookable dates, cancellation policy, and provider info. Most booking-critical values originate here.

GET{{base_url}}/item/slug/:identifier

Bearer Token Required

Path Parameters

Field	Type	Required	Description
identifier	string	REQUIRED	Item's `slug` or `id` (UUID) from GET /items response. Example: `private-full-day-old-and-new-delhi-tour`

Response — 200 OK (key fields)

{
  "data": {
    "key": "6971d307a3b2360901120b87",      // ← MongoDB ObjectId → GET /timeslots path param
    "id": "019be498-69f3-7c9d-8377-ba96b37931e6",  // ← UUID → most other APIs
    "name": "Private Full Day Old & New Delhi Tour",
    "images": ["https://cdn.rzervit.com/..."],
    "shortDesc": "Explore Delhi's heritage...",
    "bookableDates": ["2026-03-01T00:00:00.000Z", "..."],   // ← Restrict date picker to ONLY these

    "provider": {
      "bppId": "ondc.highwaydelite.com",               // ← SELECT/INIT → bppId
      "bppUri": "https://ondc.highwaydelite.com/trv14/seller",  // ← SELECT/INIT → bppUri
      "cityCode": "std:011",                         // ← SELECT/INIT → cityCode
      "id": "RZ5F0920",                               // ← SELECT/INIT → providerId
      "name": "Private Old and New Delhi Tour"
    },

    "ticketsByPackage": [
      {
        "packageId": "019be49c-de5b-7014-a4a8-2834e6b9bbe6",  // ← GET /tickets path + SELECT parent_item_id
        "packageName": "With Entry Tickets",
        "startingPrice": 9000,
        "tickets": [
          {
            "key": "6971d307a3b2360901120b8a",           // ← MongoDB ObjectId → GET /timeslots ?ticketIds=
            "id": "019be49d-..._9000.00_1000",          // ← Composite ID → SELECT items[n].id
            "name": "Per Person",
            "code": "ENTRY_PASS",
            "price": 9000,
            "minQty": 1, "maxQty": 10
          }
        ],
        "cancellation_terms": [
          { "cancellation_eligible": false }  // false = non-refundable
        ]
      }
    ]
  }
}

key vs id: The item has TWO identifiers — key (MongoDB ObjectId, looks like 6971d307...) and id (UUID, looks like 019be498-...). The Timeslots API needs key. All other APIs use id. Tickets also have both: use key for timeslot query and the composite id for SELECT.

Critical Fields — Save These for Booking

Field	Used In
data.key	GET /timeslots → path param `:itemKey`
provider.bppId	SELECT, INIT → `bppId`
provider.bppUri	SELECT, INIT → `bppUri`
provider.cityCode	SELECT, INIT → `cityCode`
provider.id	SELECT, INIT → `providerId`
ticketsByPackage[n].packageId	GET /tickets path + SELECT `items[n].parent_item_id`
ticketsByPackage[n].tickets[n].key	GET /timeslots → `ticketIds` query
ticketsByPackage[n].tickets[n].id	SELECT → `items[n].id` (use entire composite string)
bookableDates	Restrict the booking date picker to only these dates

# Search Items (Autocomplete)

Unified search-as-you-type returning both cities and attractions. Powers the global search bar. Results include a label field to differentiate city vs attraction results.

GET{{base_url}}/search-items

Bearer Token Required

Query Parameters

Field	Type	Required	Description
searchText	string	REQUIRED	Search query string. Example: `taj mahal`

Response — 200 OK

{
  "data": [
    {
      "response": "Delhi",
      "label": "city",      // "city" or "attraction"
      "id": "690db16605e92e251850de53",  // City ObjectId
      "latitude": 28.6358, "longitude": 77.22445, "state": "Delhi"
    },
    {
      "response": "Same Day Taj Mahal Sunrise Tour from Delhi, NEW DELHI",
      "label": "attraction",
      "id": "019c8dc3-c907-7f8d-9b6b-ca654c1f8b76",  // Item UUID → use in GET /item/slug/:id
      "cityCode": "std:011"
    }
  ]
}

Usage: Debounce calls by 300–500ms. Trigger after 2+ characters typed. When user selects a city result → set city context. When user selects an attraction result → navigate to item detail using id.

# Get Item Timeslots

Get available time slots for a specific item on the user's chosen booking date. Must be called after the user selects a date from the item's bookableDates. Results are required to build the SELECT payload.

GET{{base_url}}/item/:itemKey/timeslots

Bearer Token Required

Path Parameters

Field	Type	Required	Description
itemKey	string	REQUIRED	MongoDB ObjectId — the `key` field from GET /item/slug response (NOT the UUID `id`). Example: `6971d307a3b2360901120b87`

Query Parameters

Field	Type	Required	Description
date	string	REQUIRED	ISO date from the item's `bookableDates` array. Example: `2026-02-28T06:30:00.000Z`
ticketIds	string	REQUIRED	Comma-separated MongoDB ObjectIds of tickets. Use `tickets[n].key` (NOT `tickets[n].id`). Example: `6971d307a3b2360901120b8a`

Response — 200 OK

{
  "data": [
    {
      "id": "019be49e-48f1-71c0-89c6-a0aae9aa90b9",  // ← SELECT fulfillments[n].id AND items[n].fulfillment_ids
      "timestamp": null,
      "timeRangeStart": "2026-02-28T03:30:00.000Z",  // UTC → SELECT stops.time.range.start
      "timeRangeEnd":   "2026-02-28T12:30:00.000Z"   // UTC → SELECT stops.time.range.end
    }
  ]
}

Time Zone: All times are in UTC. Convert to IST (UTC+5:30) for display. The timeslot id is the ONDC fulfillment ID — save it for SELECT and INIT.

# Get Item Tickets

Get live ticket availability for a package on a specific timeslot. Returns real-time pricing, quantity limits, and the composite ticket IDs required for SELECT.

GET{{base_url}}/item/:packageId/tickets

Bearer Token Required

Path Parameters

Field	Type	Required	Description
packageId	string	REQUIRED	UUID of the package (not the item). From GET /item/slug: `ticketsByPackage[n].packageId`. Example: `019be49c-de5b-7014-a4a8-2834e6b9bbe6`

Query Parameters

Field	Type	Required	Description
timeStamp	string	REQUIRED	The start time of the selected timeslot from GET /timeslots: `data[n].timeRangeStart`. Example: `2026-02-28T03:30:00.000Z`

Response — 200 OK

{
  "data": [
    {
      "key": "6971d307a3b2360901120b8a",          // MongoDB ObjectId (for internal use)
      "id": "019be49d-..._9000.00_1000",         // ← Composite ID → SELECT items[n].id (use entire string!)
      "name": "Per Person",
      "code": "ENTRY_PASS",               // Must be ENTRY_PASS to be bookable
      "price": { "currency": "INR", "value": 9000 },
      "parentItemId": "019be49c-...",    // ← SELECT items[n].parent_item_id
      "minPeople": 1,
      "maxPeople": 10,                      // Quantity selector range
      "fulfillmentId": "019be49e-48f1-71c0-..."  // ← SELECT items[n].fulfillment_ids
    }
  ]
}

Composite Ticket ID: The id field uses the format UUID_PRICE_CAPACITY (e.g., 019be49d-..._9000.00_1000). Always use the entire string as-is in SELECT. Do NOT split, truncate, or modify it.

# Get Top Attractions

Returns top attraction names as a string array. Use for "Popular Searches" suggestion chips or search bar hints.

GET{{base_url}}/top-attractions

Bearer Token Required

No query parameters required.

{
  "data": [
    "Republic Day Ride - 2026",
    "National Gallery Of Modern Art",
    "Pradhanmantri Sangrahalaya"
    // ...
  ]
}

# Get Min/Max Price

Returns platform-wide minimum and maximum item prices. Use to initialize the price range slider on the filter UI.

GET{{base_url}}/get-min-max-price

Bearer Token Required

No query parameters required.

{
  "data": {
    "leastPrice": 1,
    "mostPrice": 78000
  }
}

← PreviousCities & Locations Next →Providers