Polling Strategy

The TripEdge API aggregates rates from multiple hotel vendors in real-time. Because vendor response times vary, you should poll the endpoints to receive the most complete results. This guide explains the recommended polling strategy.

How it works

When you make an availability or hotel request, TripEdge immediately returns with whatever results are available. As more vendors respond, subsequent requests to the same session will return additional results. The search_completed field indicates when all vendors have responded.

The polling requirements depend on your SLA and the types of rates you are ingesting. If your application requires responses within 3 seconds, you can poll at 3 seconds and use whatever results are available at that time.

Availability endpoint polling

The /availability endpoint returns hotels with their lowest rate only. This is optimized for displaying search results where you typically show one price per hotel.

Recommended polling strategy

Make the initial POST request to /availability
Poll the same endpoint every 1-2 seconds using the returned session_id
Continue polling for approximately 10 seconds or until search_completed is true
Use the final results for display

What you receive

Each poll returns:

Hotels discovered so far
The lowest_rate for each hotel (best price for quick comparison)
The lowest_brand_loyalty_rate if applicable (best price with loyalty benefits)

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "search_completed": false,
    "results": [
      {
        "hotel": {
          "id": 1234,
          "name": "Grand Hotel",
          "lowest_rate": {
            "id": "rate-uuid",
            "price_chargeable": 250.00,
            "price_currency": "USD",
            "cancellation_policy": "Refundable"
          },
          "lowest_brand_loyalty_rate": null
        },
        "rates": null
      }
    ]
  }
}

Example implementation

async function searchAvailability(searchParams) {
  // Initial request
  let response = await fetch('https://api.tripedge.com/v1/availability', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer {token}',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(searchParams)
  })

  let data = await response.json()
  const sessionId = data.data.session_id

  // Poll for 10 seconds or until complete
  const startTime = Date.now()
  const maxPollTime = 10000 // 10 seconds

  while (!data.data.search_completed && (Date.now() - startTime) < maxPollTime) {
    await sleep(1500) // Wait 1.5 seconds between polls

    response = await fetch(
      `https://api.tripedge.com/v1/availability/debug/${sessionId}`,
      { headers: { 'Authorization': 'Bearer {token}' } }
    )
    data = await response.json()
  }

  return data
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms))
}

Hotel endpoint polling

The /hotel/:hotel_id/:session_id endpoint returns all available rates for a specific hotel. Poll this endpoint to ensure you have the complete list of room types and rate options.

Recommended polling strategy

Make the initial GET request to /hotel/:hotel_id/:session_id
Poll every 1 second
Continue polling for approximately 5 seconds or until search_completed is true
Display all rates to the user

What you receive

Each poll returns:

Complete hotel details
All rates discovered so far (multiple room types, board options, cancellation policies)

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "search_completed": true,
    "hotel": { /* full hotel details */ },
    "rates": [
      {
        "id": "rate-1",
        "rooms": [{ "name": "Deluxe King", "board": "BB" }],
        "price_chargeable": 250.00,
        "cancellation_policy": "Refundable"
      },
      {
        "id": "rate-2",
        "rooms": [{ "name": "Standard Queen", "board": "RO" }],
        "price_chargeable": 180.00,
        "cancellation_policy": "NonRefundable"
      },
      {
        "id": "rate-3",
        "rooms": [{ "name": "Suite", "board": "FB" }],
        "price_chargeable": 450.00,
        "cancellation_policy": "Refundable"
      }
    ]
  }
}

Example implementation

async function getHotelRates(hotelId, sessionId) {
  const url = `https://api.tripedge.com/v1/hotel/${hotelId}/${sessionId}`

  let response = await fetch(url, {
    headers: { 'Authorization': 'Bearer {token}' }
  })
  let data = await response.json()

  // Poll for 5 seconds or until complete
  const startTime = Date.now()
  const maxPollTime = 5000 // 5 seconds

  while (!data.data.search_completed && (Date.now() - startTime) < maxPollTime) {
    await sleep(1000) // Wait 1 second between polls

    response = await fetch(url, {
      headers: { 'Authorization': 'Bearer {token}' }
    })
    data = await response.json()
  }

  return data
}

Adjusting for your SLA

The 10-second and 5-second recommendations are designed to capture results from most vendors. However, you should adjust based on your requirements:

Your SLA	Availability Poll Time	Hotel Poll Time	Trade-off
3 seconds	3 seconds	2 seconds	Fastest response, may miss some vendors
5 seconds	5 seconds	3 seconds	Good balance for most use cases
10 seconds	10 seconds	5 seconds	Maximum coverage, slower perceived speed
No limit	Until `search_completed`	Until `search_completed`	Complete results, variable timing

Considerations

Rate types matter: Some vendors respond faster than others. If you only need certain rate types, you may receive them earlier.
User experience: Consider showing partial results immediately and updating the UI as more results arrive.
Progressive loading: Display a loading indicator while polling, updating the hotel count as new results come in.

Best practices

Show results progressively

Do not wait for polling to complete before showing results. Update your UI as new hotels/rates arrive:

async function searchWithProgressiveResults(searchParams, onUpdate) {
  let response = await fetch('https://api.tripedge.com/v1/availability', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer {token}',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(searchParams)
  })

  let data = await response.json()
  const sessionId = data.data.session_id

  // Show initial results immediately
  onUpdate(data.data.results, data.data.search_completed)

  const startTime = Date.now()

  while (!data.data.search_completed && (Date.now() - startTime) < 10000) {
    await sleep(1500)

    response = await fetch(
      `https://api.tripedge.com/v1/availability/debug/${sessionId}`,
      { headers: { 'Authorization': 'Bearer {token}' } }
    )
    data = await response.json()

    // Update UI with new results
    onUpdate(data.data.results, data.data.search_completed)
  }

  return data
}

Cache the session ID

The session ID is valid for the duration shown in expires_at. Reuse it when:

The user returns to the search results from a hotel detail page
The user changes sort/filter options on the same search
You need to refresh results without a new search

Handle the search_completed flag

if (data.data.search_completed) {
  // All vendors have responded - final results
  hideLoadingIndicator()
} else {
  // Still waiting for some vendors
  showPartialResultsIndicator()
}